{ "openapi": "3.0.1", "info": { "title": "Careem POS API", "description": "Careem POS API enables partners to provide restaurants a convenient way to manage Careem orders as part of their regular operations.\n\nYou may download the OpenAPI specification here.\n# Overview\n\nThis section discusses challenges that arise from manual integration, followed by an overview of Careem's POS API and its advantages.\n\n## Challenges with manual integration\n\nManual integration with POS systems is known to be associated with many problems. Some of the common problems have been highlighted below:\n\n- Punching data manually is **error-prone**. This can cause data inconsistencies in the POS system, leading to order cancellations.\n- Punching data manually is **time-consuming**. This slows down order processing and impacts customer satisfaction directly.\n- Punching data manually can be extremely **demanding** during high volumes of orders, leading to burnout.\n- Punching data manually is **unscalable**. This can make it challenging for businesses to scale their operations.\n\n## POS API overview\n\nCareem offers its own integration API, which partners can use to seamlessly integrate with their POS systems.\n\nThe **Store API** allows partners to create and manage their stores on Careem's platform. Store management includes the following key features:\n\n- Enable/disable POS integration\n- Mark the store online/offline\n- Update operational hours\n\nThe **Catalog API** allows partners to create and manage catalogs for their stores. The API also includes sending catalog sync notifications to a partner's webhook. Catalog management includes the following key features:\n\n- Support partial catalogs\n- Track catalog sync status\n- Reset catalog\n- Update item availability\n\nThe **Order API** allows partners to retrieve and manage orders. The API also includes sending order notifications to a partner's webhook. Order management includes the following key features:\n\n- Accept/cancel orders\n- Mark order as ready\n- Tag orders\n- Receive order notifications via webhook\n\n## Benefits\n\nWith Careem's integration API, partners can take advantage of the following benefits:\n\n- Increased order accuracy\n- Increased operational excellence\n- Enhanced customer experience\n- Improved order fulfillment KPIs\n\n# Getting started\n\nThis section serves as a starting point for using our API.\n\n## Pre-requisites\n\nBefore you begin to use our APIs, please ensure:\n\n- Completion of contract and submission of essential legal and regulatory compliance documentation as per instructions by our commercial team. If you've not done so already, please feel free to reach out to them.\n- Received approval from our information security & legal teams.\n\nFurthermore, it is also necessary to complete the following tasks:\n\n### Webhook configuration\n\nTo receive catalog sync and order notifications from our platform, you need to generate and share the following two values with our engineering team before integration:\n\n- **A webhook URL:** a secure HTTPS endpoint (port 443, valid SSL certificate) that can receive `POST` requests. This is where we send notifications to your system.\n- **An API key secret:** a secret value that **you generate** (we recommend a random, hard-to-guess string such as a UUID) and **share with us**.\n\n**How the API key is used:** On every webhook request we send you, we include the exact secret you shared with us in a header named `x-careem-api-key`. Your system should validate every incoming webhook by checking that this header matches the secret you provided, and reject any request where it does not match or is missing. This is how you confirm the request genuinely originated from Careem and not a third party.\n\nKeep this secret confidential. If you believe it has been exposed, contact our engineering team so we can coordinate rotating it.\n\n#### Example of the webhook request header\n\n```text\nx-careem-api-key: a12345f-1337-4bff-8e6b-6b38a221322f\n```\n\n## Integration Process Overview\n\n```mermaid\nflowchart TD\n A[Timeline agreement] --> B[Setup client]\n B --> C[Setup test brand]\n C --> D[Setup test branch]\n D --> E[Map the test branch]\n E --> F[Push catalog]\n F --> G[Share SuperApp APK]\n G --> H[Provide ongoing support]\n H --> I[Perform end-to-end testing with QA]\n I --> J[Production rollout]\n```\n\n### Timeline agreement\n\nWe require due dates from our partners for completion of their development work so we can make a project plan accordingly.\n\n### Setup client\n\nWe would set up an OAuth client on our end and share its credentials with you.\n\n### Setup test brand\n\nThe partner would create a test brand via the brand API.\n\n### Setup test branch\n\nThe partner would create a test branch (linked to the test brand) via the branch API.\n\nAdditionally, the partner would also enable POS integration for the test branch (also via the branch API).\n\n### Map the test branch\n\nUpon creation of the test branch, the partner would request the operations team to map the test branch to an outlet on our platform.\n\n### Push catalog\n\nThe partner would push a catalog for the test branch via the catalog API.\n\n### Share SuperApp APK\n\nThe engineering team would share an APK for the SuperApp so that the partner can validate their pushed catalog and also perform their own testing.\n\n### Provide ongoing support\n\nThe engineering team will provide ongoing assistance to the partner during the development process, as needed to address any issues that may arise.\n\n### Perform end-to-end testing with QA\n\nOnce the partner completes their development, our QA team would assist in scheduling a one-hour testing session with your team. If any issues arise, they will be addressed by the engineering team.\n\n### Production rollout\n\nThe rollout for production will follow the same steps mentioned above, starting from setting up a client all the way to pushing catalogs.\n\n## API endpoints\n\nThe API operates in three countries, namely, UAE (Dubai), Jordan and KSA.\n\n### Staging environment\n\nYou can test your integration with the API in this environment. The base URL for the staging environment is:\n\n[https://apigateway-stg.careemdash.com/pos/api/v1](https://apigateway-stg.careemdash.com/pos/api/v1)\n\n#### Production environment\n\nThe base URL for the production environment is:\n\n[https://apigateway.careemdash.com/pos/api/v1](https://apigateway.careemdash.com/pos/api/v1)\n\n## Pagination\nAPI requests that return list of resources will be paginated to `20` resources by default. To navigate through the list of resources, you can use the `page_number` query parameter. You can also specify a different number of resources on each page by using the `page_size` parameter, with a maximum limit of 20.\n\n## Rate limiting\n\nIn order to prevent abuse and ensure overall system stability, the API implements rate limiting. We expect our partners to adhere to the following thresholds:\n\n- **Catalog API**\n - 1 catalog sync per branch every 2 minutes\n - 50 catalog syncs across all branches per minute\n - No more than 8,500 items can be provided in a catalog sync\n\n- **Item availability API**\n - No more than 40 items can be updated in a single API call\n\nYou must apply necessary checks on your end to handle 429 (too many requests) status code from our APIs.\n\n## Webhook availability\n\nOur API supports up to 4 retries for failed requests to the partner's webhook endpoint, with a maximum of 5 attempts in total, including the initial call.\n\nIn case of the webhook endpoint being down, any event sent after the API exhausts its retries would be lost, making it crucial for partners to ensure its high availability.", "version": "2.1.0", "x-logo": { "url": "https://docs.careemnow.com/logo.png", "altText": "Careem" } }, "servers": [ { "url": "https://apigateway.careemdash.com/pos/api/v1", "description": "production server" }, { "url": "https://apigateway-stg.careemdash.com/pos/api/v1", "description": "staging server" } ], "security": [ { "CareemIDPClientCredentials": [ "pos" ] } ], "tags": [ { "name": "Auth overview", "description": "Our API uses OAuth2 and specifically **OAuth2 Client Credentials Grant** to authenticate incoming requests.\n\nThis is a general diagram of how API requests are authenticated.\n\n```mermaid\nsequenceDiagram\n participant Client\n participant Careem Identity Provider\n participant Careem API\n\n Client->>Careem Identity Provider: Request access token\n Careem Identity Provider->>Careem Identity Provider: Authorize access token request\n Careem Identity Provider->>Client: Respond with access token\n Client->>Careem API: Request protected resource\n Careem API->>Careem API: Authenticate request with access token\n Careem API->>Client: Respond with protected resource\n```\n\nYou may also find an overview of the flow [here.](https://www.oauth.com/oauth2-servers/access-tokens/client-credentials/)\n\n", "x-displayName": "Overview" }, { "name": "Auth endpoints", "description": "This section covers endpoints related to authentication.", "x-displayName": "Endpoints" }, { "name": "Auth token", "description": "The token you receive from our identity provider is used to authenticate every request you send. The token should be embedded into the request's Authorization header with \"Bearer\" prefix.\n\n# Scopes\n\nCurrently, all the available API endpoints support a single scope: pos\n\n# Expiry\n\nThe token has an expiry of 24 hours, but you can renew the token any time you want by requesting a new token using the same flow.\n\n# Renewal\n\nThe request of a new token does not invalidate the existing token(s). This means that if you have multiple services or multiple instances of the same service, they could all request the access token separately, so that you would not have to maintain a shared state between them. On the other hand, sharing the same access token between several services/instances is also fine.\n\nIn general, it is a good idea to not wait all the way till token expiry, but rather request a new token a bit in advance.\n", "x-displayName": "Authorization token" }, { "name": "Auth rate limiting", "description": "Please store the received token on your side and do not try to request a new token every time you do an API request. This might potentially lead to unneeded rate-limiting or even IP block and might require manual intervention. If this does happen, please reach out to your Careem contact person.", "x-displayName": "Rate limiting" }, { "name": "Store API overview", "description": "A brand is a unique identity that sets a company apart from its competitors. For example, KFC is a brand. Subway is a brand. Burger King is a brand too.\n\nA branch is a physical outlet from which orders are picked up. For example, KFC located at Dubai Marina Mall is a branch. To create a branch, a brand must be created first.\n\nThere can be multiple branches associated with one brand but a branch can only be associated with one brand.\n\nThe **Store API** allows partners to create and manage their stores on Careem's platform.", "x-displayName": "Overview" }, { "name": "Store API components", "description": "- **List brands**\n - To view all the brands that you've created, use the GET /brands endpoint\n- **Create a brand**\n - To create a brand, use the POST /brands endpoint\n- **Fetch a brand**\n - To fetch an existing brand by its ID, use the GET /brands/{brand_id} endpoint\n- **Update a brand**\n - Update a brand using the PUT /brands/{brand_id} endpoint\n- **Delete a brand**\n - Delete a brand using the DELETE /brands/{brand_id} endpoint\n- **List branches**\n - To view all the branches that you've created, use the GET /branches endpoint\n- **Create a branch**\n - To create a branch, use the PUT /branches endpoint\n- **Fetch a branch**\n - To fetch an existing branch by its ID, use the GET /branches/{branch_id} endpoint\n- **Update a branch**\n - Update a branch using the PUT /branches/{branch_id} endpoint\n- **Delete a branch**\n - Delete a branch using the DELETE /branches/{branch_id} endpoint\n- **Toggle branch POS integration**\n - Use the PATCH /branches/{branch_id}/status endpoint to enable or disable POS integration for a branch. By default, this toggle is disabled when a branch gets created. Once enabled, orders will flow through partner's POS systems.\n- **Update branch status on SuperApp**\n - Use the POST /branches/{branch_id}/visibility/status endpoint to update the branch status on SuperApp. If the status is set to active, the branch would appear on the SuperApp and customers would be able to place orders. However, if the status is set to inactive, the branch would appear on the SuperApp but customers would not be able to place orders.\n - Use the POST /branches/{branch_id}/visibility/status/expiries to set a branch's status to inactive for a limited period of time. Once the time passes, the branch would become active again.\n- **Set and retrieve branch operational hours**\n - Set and retrieve operational hours for the branch via the PUT /operational-hours and GET /operational-hours endpoints.\n", "x-displayName": "Components" }, { "name": "Store API operational hours", "description": "This section provides information on operational hours and shifts.\n\nPlease note:\n\n- 24 hours format (HH:MM local time) to be followed for `start_at` and `end_at`\n- `end_at` cannot be 00:00\n- Day of the week will be broken into two entries if there are two separate shifts in a day\n\nBelow is a sample request payload for a branch which is operational from 11 AM to 2 AM on every day except Friday:\n
\nExpand to see the payload\n\n```json\n{\n \"operational_hours\": [\n {\n \"shifts\": [\n {\n \"start_time\": \"11:00\",\n \"end_time\": \"23:59\"\n },\n {\n \"start_time\": \"00:00\",\n \"end_time\": \"02:00\"\n }\n ],\n \"active\": true,\n \"day_of_week\": 1\n },\n {\n \"shifts\": [\n {\n \"start_time\": \"11:00\",\n \"end_time\": \"23:59\"\n },\n {\n \"start_time\": \"00:00\",\n \"end_time\": \"02:00\"\n }\n ],\n \"active\": true,\n \"day_of_week\": 2\n },\n {\n \"shifts\": [\n {\n \"start_time\": \"11:00\",\n \"end_time\": \"23:59\"\n },\n {\n \"start_time\": \"00:00\",\n \"end_time\": \"02:00\"\n }\n ],\n \"active\": true,\n \"day_of_week\": 3\n },\n {\n \"shifts\": [\n {\n \"start_time\": \"11:00\",\n \"end_time\": \"23:59\"\n },\n {\n \"start_time\": \"00:00\",\n \"end_time\": \"02:00\"\n }\n ],\n \"active\": true,\n \"day_of_week\": 4\n },\n {\n \"shifts\": [\n {\n \"start_time\": \"11:00\",\n \"end_time\": \"23:59\"\n },\n {\n \"start_time\": \"00:00\",\n \"end_time\": \"02:00\"\n }\n ],\n \"active\": true,\n \"day_of_week\": 5\n },\n {\n \"shifts\": [\n {\n \"start_time\": \"00:00\",\n \"end_time\": \"02:00\"\n }\n ],\n \"active\": true,\n \"day_of_week\": 6\n },\n {\n \"shifts\": [\n {\n \"start_time\": \"11:00\",\n \"end_time\": \"23:59\"\n }\n ],\n \"active\": true,\n \"day_of_week\": 7\n }\n ]\n}\n```\n
\n\n**Clarification**\n\nWhen we say that a branch is operational from 11 AM to 2 AM on day X, we actually include two days. Therefore, this is how it is supposed to look like:\n\n- **Day X** - 11 AM - 12 AM\n- **Day X + 1** - 12 AM - 2 AM\n\nThat is the reason why there's a shift for Friday in the above JSON otherwise it would contradict our statement that the branch is not operational on Friday.", "x-displayName": "Operational hours and shifts" }, { "name": "Store API endpoints", "description": "This section covers endpoints for the store API.", "x-displayName": "Endpoints" }, { "name": "Store API flows", "description": "This section covers flows for the store API.\n\n# Create brand\n\n```mermaid\nsequenceDiagram\nparticipant Client\nparticipant Brand API\nClient->>Brand API: Request to create a new brand via PUT /brands\nBrand API->>Brand API: Verify uniqueness of the name\nalt name is unique\nBrand API->>Brand API: Create new brand\nBrand API-->>Client: HTTP 200 OK\nelse name is in use\nBrand API-->>Client: HTTP 409 Conflict\nend\n```\n\n# Create branch\n\n```mermaid\nsequenceDiagram\nparticipant Client\nparticipant Store API\nClient->>Store API: Request to create a new branch via PUT /branches\nStore API->>Store API: Verify uniqueness of the name\nalt name is unique\nStore API->>Store API: Create new branch\nStore API-->>Client: HTTP 200 OK\nelse name is in use\nStore API-->>Client: HTTP 409 Conflict\nend\n```", "x-displayName": "Flows" }, { "name": "Catalog API overview", "description": "A catalog represents the menu for a branch. It includes a hierarchical structure consisting of categories, subcategories, items, groups, and options.\n\n- **Categories**\n - Classification of items based on a common trait.\n - An item can be associated with multiple categories.\n - A category is required to create items in a catalog.\n - For example, breakfast, appetizers and drinks are categories.\n- **Subcategories**\n - A subcategory can be used for further division within a category.\n - A subcategory is optional when creating an item.\n - For example, the beverages category can be broken down into hot and cold items.\n- **Items**\n - Product or dish in a restaurant.\n - For example, fried eggs in the breakfast category.\n- **Groups**\n - Refers to the set of options/choices/add-ons/customizations.\n - The group is nested within an item, allowing customers to customize the item as needed.\n - For example, an option group can be 'Choose your Sauce' for the item 'Beef Burger'.\n- **Options**\n - Represents options for a selected group.\n - For example, options can be Mushroom Sauce, BBQ Sauce, etc. for the group 'Choose your Sauce' under the item 'Beef Burger'.\n- **Nested groups**\n - Identical to groups in their nature, but they are associated with options.\n - For example, a nested group can be 'Choose condiments' for the option 'French Fries' under the group 'Add a side item'.\n- **Nested options**\n - Identical to options in their nature, but they are associated with nested groups.\n - For example, options can be Ketchup, Mayonnaise etc. for the nested group 'Choose condiments'.\n\nThe following visualization should give you a clear understanding of the hierarchy described above.\n\n![Catalog hierarchy](/diagrams/hierarchy.svg)\n\nA branch can have multiple catalogs associated with itself. However, only one catalog can be active at a given point in time.\n\nThe **Catalog API** allows partners to create and manage catalogs for their branch. The API also includes sending catalog sync notifications to a partner's webhook.", "x-displayName": "Overview" }, { "name": "Catalog API components", "description": "- **Upload catalog**\n - Upload catalog for a branch using the PUT /catalogs endpoint. This endpoint supports partial catalogs for subsequent invocations for a branch once its complete catalog has been uploaded.\n- **Check catalog upload request status**\n - Use the GET /catalogs/status/{request_id} endpoint to fetch the status of a catalog upload request by its ID.\n- **Update item(s) availability**\n - Update the availability of a single or multiple items (maximum: 40) of a catalog via the PATCH /catalogs/{catalog_id}/items endpoint.\n- **Reset catalog**\n - Reset a catalog using the DELETE /catalogs endpoint. This endpoint is ONLY meant to be used in case of data inconsistencies.\n- **Receive catalog sync notifications**\n - A catalog sync notification would be posted on your webhook in either of the following scenarios:\n - A catalog has successfully synced with our platform.\n - A catalog has failed to sync with our platform.", "x-displayName": "Components" }, { "name": "Catalog API endpoints", "description": "This section covers endpoints for the catalog API.", "x-displayName": "Endpoints" }, { "name": "Catalog API webhook events", "description": "The API supports the following webhook events:\n\n| Event | Trigger |\n|------------------------|---------------------------------|\n| CATALOG_STATUS_UPDATED | A catalog request has processed |", "x-displayName": "Webhook events" }, { "name": "Catalog API flows", "description": "This section covers flows for the catalog API.\n\n# Upload catalog\n\n```mermaid\nsequenceDiagram\nparticipant Client\nparticipant Client webhook\nparticipant Catalog API\nClient->>Catalog API: Request to upload a new catalog via PUT /catalogs\nCatalog API->>Catalog API: Verify mapping of branch\nalt branch is mapped\nCatalog API->>Catalog API: Verify amount of items in catalog\nalt amount does not exceed threshold\nCatalog API->>Catalog API: Verify if there is a running catalog upload for the branch\nalt there is no running catalog upload\nCatalog API->>Catalog API: Upload catalog\nCatalog API-->>Client: HTTP 200 OK\nCatalog API-->>Client webhook: Post CATALOG_REQUEST_STATUS_UPDATED event\nelse there is already a running catalog upload\nCatalog API-->>Client: HTTP 409 Conflict\nend\nelse amount exceeds threshold\nCatalog API-->>Client: HTTP 400 Bad Request\nend\nelse branch is unmapped\nCatalog API-->>Client: HTTP 400 Bad Request\nend\nopt fetch catalog upload request status\nClient->Catalog API: Request to fetch catalog upload request status\nCatalog API-->>Client: HTTP 200 OK\nend\n```\n", "x-displayName": "Flows" }, { "name": "Catalog API sample payloads", "description": "Here are a few sample payloads for ease of use.\n\n# Create full catalog\n\n**Creating a catalog for first time.**\n\n
\nExpand to see the payload\n\n```json\n{\n \"diff\": false,\n \"catalog\": {\n \"id\": \"DefaultCatalog\",\n \"name\": \"Default\",\n \"include_tax\": true,\n \"tax\": 5.2,\n \"avg_price\": 12.25,\n \"file\": \"https://loremflickr.com/cache/resized/65535_49625844823_baed6d35f9_320_240_g.jpg\",\n \"currency_id\": 1,\n \"category_ids\": [\n \"breakfast\",\n \"snacks\",\n \"test-category\"\n ]\n },\n \"categories\": [\n {\n \"id\": \"breakfast\",\n \"name\": \"breakfast\",\n \"name_localized\": {\n \"en\": \"Breakfast\",\n \"ar\": \"\"\n },\n \"description\": \"All the breakfast items\",\n \"description_localized\": {\n \"en\": \"All breakfast items\",\n \"ar\": \"\"\n },\n \"preparation_time\": 20,\n \"operational_hours\": [\n {\n \"shifts\": [\n {\n \"start_time\": \"10:00\",\n \"end_time\": \"12:00\"\n }\n ],\n \"active\": true,\n \"day_of_week\": 5\n }\n ],\n \"items\": [\n \"pancakes\",\n \"shawarma\"\n ]\n },\n {\n \"id\": \"snacks\",\n \"name\": \"snacks\",\n \"name_localized\": {\n \"en\": \"Snacks\",\n \"ar\": \"\"\n },\n \"description\": \"Get recharged with snacks\",\n \"description_localized\": {\n \"en\": \"Get recharged with snacks\",\n \"ar\": \"\"\n },\n \"preparation_time\": 20,\n \"operational_hours\": [\n {\n \"shifts\": [\n {\n \"start_time\": \"10:00\",\n \"end_time\": \"12:00\"\n }\n ],\n \"active\": true,\n \"day_of_week\": 5\n }\n ],\n \"items\": []\n },\n {\n \"id\": \"test-category\",\n \"name\": \"Test category\",\n \"name_localized\": {\n \"en\": \"Test category\",\n \"ar\": \"\"\n },\n \"description\": \"Description for category\",\n \"description_localized\": {\n \"en\": \"Description for category\",\n \"ar\": \"\"\n },\n \"preparation_time\": 20,\n \"operational_hours\": [\n {\n \"shifts\": [\n {\n \"start_time\": \"10:00\",\n \"end_time\": \"12:00\"\n }\n ],\n \"active\": true,\n \"day_of_week\": 5\n }\n ],\n \"sub_categories\": [\n \"test-subcategory\"\n ],\n \"items\": []\n }\n ],\n \"sub_categories\": [\n {\n \"id\": \"test-subcategory\",\n \"name\": \"Subcategory\",\n \"name_localized\": {\n \"en\": \"Subcategory\",\n \"ar\": \"\"\n },\n \"description\": \"Description for subcategory\",\n \"description_localized\": {\n \"en\": \"Description for subcategory\",\n \"ar\": \"\"\n },\n \"preparation_time\": 20,\n \"operational_hours\": [\n {\n \"shifts\": [\n {\n \"start_time\": \"10:00\",\n \"end_time\": \"12:00\"\n }\n ],\n \"active\": true,\n \"day_of_week\": 5\n }\n ],\n \"items\": []\n }\n ],\n \"items\": [\n {\n \"id\": \"pancakes\",\n \"name\": \"Pancakes\",\n \"name_localized\": {\n \"en\": \"Pancakes\",\n \"ar\": \"\"\n },\n \"description\": \"Fresh egg and chocolate pancakes\",\n \"description_localized\": {\n \"en\": \"Fresh egg and chocolate pancakes\",\n \"ar\": \"\"\n },\n \"active\": true,\n \"price\": 20,\n \"calorie_counts\": \"200\",\n \"allergic_information\": \"allergic to eggs\",\n \"upc\": \"5070000354101\",\n \"location\": {\n \"aisle\": \"2\",\n \"row\": \"C\",\n \"zone\": \"1\",\n \"section\": \"4\"\n },\n \"operational_hours\": [\n {\n \"shifts\": [\n {\n \"start_time\": \"10:00\",\n \"end_time\": \"12:00\"\n }\n ],\n \"active\": true,\n \"day_of_week\": 5\n }\n ],\n \"media\": \"https://picsum.photos/300.jpg\",\n \"groups\": [\n \"sauces\",\n \"syrups\"\n ]\n },\n {\n \"id\": \"shawarma\",\n \"name\": \"Shawarma\",\n \"name_localized\": {\n \"en\": \"Shawarma\",\n \"ar\": \"\"\n },\n \"description\": \"Fresh and hot chicken shawarma\",\n \"description_localized\": {\n \"en\": \"Fresh and hot chicken shawarma\",\n \"ar\": \"\"\n },\n \"active\": true,\n \"price\": 40,\n \"calorie_counts\": \"500\",\n \"allergic_information\": \"allergic to ketchup\",\n \"upc\": \"5070000354118\",\n \"location\": {\n \"aisle\": \"2\",\n \"row\": \"C\",\n \"zone\": \"1\",\n \"section\": \"4\"\n },\n \"operational_hours\": [\n {\n \"shifts\": [\n {\n \"start_time\": \"10:00\",\n \"end_time\": \"12:00\"\n }\n ],\n \"active\": true,\n \"day_of_week\": 5\n }\n ],\n \"media\": \"https://picsum.photos/300.jpg\",\n \"groups\": [\n \"sauces\",\n \"syrups\"\n ]\n }\n ],\n \"groups\": [\n {\n \"id\": \"syrups\",\n \"name\": \"Choose syrups\",\n \"name_localized\": {\n \"en\": \"Choose syrups\",\n \"ar\": \"\"\n },\n \"description\": \"Dressings for the salad\",\n \"description_localized\": {\n \"en\": \"Syrup for pancakes\",\n \"ar\": \"\"\n },\n \"multi_select\": false,\n \"min\": 2,\n \"max\": 4,\n \"options\": [\n \"maple\",\n \"sugar\"\n ]\n },\n {\n \"id\": \"sauces\",\n \"name\": \"Choose sauce\",\n \"name_localized\": {\n \"en\": \"Choose sauce\",\n \"ar\": \"\"\n },\n \"description\": \"Sauce for your main dish\",\n \"description_localized\": {\n \"en\": \"Sauce for dressing\",\n \"ar\": \"\"\n },\n \"min\": 2,\n \"max\": 4,\n \"options\": [\n \"barbecue\",\n \"soy\"\n ]\n }\n ],\n \"options\": [\n {\n \"id\": \"maple\",\n \"name\": \"Maple syrup\",\n \"name_localized\": {\n \"en\": \"Maple syrup\",\n \"ar\": \"\"\n },\n \"active\": true,\n \"price\": 20\n },\n {\n \"id\": \"sugar\",\n \"name\": \"Sugar syrup\",\n \"name_localized\": {\n \"en\": \"Sugar syrup\",\n \"ar\": \"\"\n },\n \"active\": true,\n \"price\": 20\n },\n {\n \"id\": \"barbecue\",\n \"name\": \"Barbecue sauce\",\n \"name_localized\": {\n \"en\": \"Barbecue sauce\",\n \"ar\": \"\"\n },\n \"active\": true,\n \"price\": 20\n },\n {\n \"id\": \"soy\",\n \"name\": \"Soy sauce\",\n \"name_localized\": {\n \"en\": \"Soy sauce\",\n \"ar\": \"\"\n },\n \"active\": true,\n \"price\": 20\n }\n ]\n}\n```\n
\n\n# Update/override full catalog\n\n**Updating a catalog without difference by sending whole catalog. No entities can be deleted by setting deleted as true when diff is false. Entities which are not sent in the payload will be deleted by finding the difference from previously existing entities.**\n\n
\nExpand to see the payload\n\n```json\n{\n \"diff\": false,\n \"catalog\": {\n \"id\": \"DefaultCatalog\",\n \"name\": \"Default\",\n \"include_tax\": true,\n \"tax\": 5.2,\n \"avg_price\": 12.25,\n \"file\": \"https://loremflickr.com/cache/resized/65535_49625844823_baed6d35f9_320_240_g.jpg\",\n \"currency_id\": 1,\n \"category_ids\": [\n \"breakfast\"\n ]\n },\n \"categories\": [\n {\n \"id\": \"breakfast\",\n \"name\": \"Default\",\n \"name_localized\": {\n \"en\": \"Breakfast\",\n \"ar\": \"\"\n },\n \"description\": \"All the breakfast items\",\n \"description_localized\": {\n \"en\": \"All breakfast items\",\n \"ar\": \"\"\n },\n \"preparation_time\": 20,\n \"operational_hours\": [\n {\n \"shifts\": [\n {\n \"start_time\": \"10:00\",\n \"end_time\": \"12:00\"\n }\n ],\n \"active\": true,\n \"day_of_week\": 5\n }\n ],\n \"items\": [\n \"pancakes\",\n \"shawarma\"\n ]\n }\n ],\n \"items\": [\n {\n \"id\": \"pancakes\",\n \"name\": \"Pancakes\",\n \"name_localized\": {\n \"en\": \"Pancakes\",\n \"ar\": \"\"\n },\n \"description\": \"Fresh egg and chocolate pancakes\",\n \"description_localized\": {\n \"en\": \"Fresh egg and chocolate pancakes\",\n \"ar\": \"\"\n },\n \"active\": true,\n \"price\": 20,\n \"calorie_counts\": \"200\",\n \"allergic_information\": \"allergic to eggs\",\n \"upc\": \"5070000354118\",\n \"location\": {\n \"aisle\": \"2\",\n \"row\": \"C\",\n \"zone\": \"1\",\n \"section\": \"4\"\n },\n \"operational_hours\": [\n {\n \"shifts\": [\n {\n \"start_time\": \"10:00\",\n \"end_time\": \"12:00\"\n }\n ],\n \"active\": true,\n \"day_of_week\": 5\n }\n ],\n \"media\": \"https://picsum.photos/300.jpg\",\n \"groups\": [\n \"sauces\",\n \"syrups\"\n ]\n },\n {\n \"id\": \"shawarma\",\n \"name\": \"Shawarma\",\n \"name_localized\": {\n \"en\": \"Shawarma\",\n \"ar\": \"\"\n },\n \"description\": \"Fresh and hot chicken shawarma\",\n \"description_localized\": {\n \"en\": \"Fresh and hot chicken shawarma\",\n \"ar\": \"\"\n },\n \"active\": true,\n \"price\": 40,\n \"calorie_counts\": \"500\",\n \"allergic_information\": \"allergic to ketchup\",\n \"upc\": \"5070000354101\",\n \"location\": {\n \"aisle\": \"2\",\n \"row\": \"C\",\n \"zone\": \"1\",\n \"section\": \"4\"\n },\n \"operational_hours\": [\n {\n \"shifts\": [\n {\n \"start_time\": \"10:00\",\n \"end_time\": \"12:00\"\n }\n ],\n \"active\": true,\n \"day_of_week\": 5\n }\n ],\n \"media\": \"https://picsum.photos/300.jpg\",\n \"groups\": [\n \"sauces\",\n \"syrups\"\n ]\n }\n ],\n \"groups\": [\n {\n \"id\": \"syrups\",\n \"name\": \"Choose syrups\",\n \"name_localized\": {\n \"en\": \"Choose syrups\",\n \"ar\": \"\"\n },\n \"description\": \"Dressings for the salad\",\n \"description_localized\": {\n \"en\": \"Syrup for pancakes\",\n \"ar\": \"\"\n },\n \"multi_select\": false,\n \"min\": 1,\n \"max\": 4,\n \"options\": [\n \"maple\"\n ]\n },\n {\n \"id\": \"sauces\",\n \"name\": \"Choose sauce\",\n \"name_localized\": {\n \"en\": \"Choose sauce\",\n \"ar\": \"\"\n },\n \"description\": \"Sauce for your main dish\",\n \"description_localized\": {\n \"en\": \"Sauce for dressing\",\n \"ar\": \"\"\n },\n \"min\": 2,\n \"max\": 4,\n \"options\": [\n \"tomato\",\n \"mustard\",\n \"mayo\"\n ]\n }\n ],\n \"options\": [\n {\n \"id\": \"maple\",\n \"name\": \"Maple Syrup\",\n \"name_localized\": {\n \"en\": \"Maple syrup\",\n \"ar\": \"\"\n },\n \"active\": true,\n \"price\": 20\n },\n {\n \"id\": \"tomato\",\n \"name\": \"Tomato sauce\",\n \"name_localized\": {\n \"en\": \"Tomato sauce\",\n \"ar\": \"\"\n },\n \"active\": true,\n \"price\": 20\n },\n {\n \"id\": \"mustard\",\n \"name\": \"Mustard sauce\",\n \"name_localized\": {\n \"en\": \"Soy sauce\",\n \"ar\": \"\"\n },\n \"active\": true,\n \"price\": 20\n },\n {\n \"id\": \"mayo\",\n \"name\": \"Mayo sauce\",\n \"name_localized\": {\n \"en\": \"Mayo sauce\",\n \"ar\": \"\"\n },\n \"active\": true,\n \"price\": 20\n }\n ]\n}\n```\n
\n\n# Update partial catalog\n\n**Update a catalog with difference. The entities to be deleted should have deleted set as true. Other entities will be added or updated by finding the difference from previously existing entities.**\n\n
\nExpand to see the payload\n\n```json\n{\n \"diff\": true,\n \"catalog\": {\n \"id\": \"DefaultCatalog\",\n \"name\": \"Default\",\n \"include_tax\": true,\n \"tax\": 5.2,\n \"avg_price\": 12.25,\n \"file\": \"https://loremflickr.com/cache/resized/65535_49625844823_baed6d35f9_320_240_g.jpg\",\n \"currency_id\": 1,\n \"category_ids\": [\n \"breakfast\",\n \"snacks\"\n ]\n },\n \"categories\": [\n {\n \"id\": \"breakfast\",\n \"name\": \"Default\",\n \"name_localized\": {\n \"en\": \"Breakfast\",\n \"ar\": \"\"\n },\n \"description\": \"All the breakfast items\",\n \"description_localized\": {\n \"en\": \"All breakfast items\",\n \"ar\": \"\"\n },\n \"preparation_time\": 20,\n \"operational_hours\": [\n {\n \"shifts\": [\n {\n \"start_time\": \"10:00\",\n \"end_time\": \"12:00\"\n }\n ],\n \"active\": true,\n \"day_of_week\": 5\n }\n ],\n \"sub_categories\": [\n \"subcategory\"\n ],\n \"items\": [\n \"pancakes\",\n \"shawarma\"\n ]\n },\n {\n \"id\": \"snacks\",\n \"deleted\": true\n }\n ],\n \"sub_categories\": [\n {\n \"id\": \"subcategory\",\n \"name\": \"Subcategory\",\n \"name_localized\": {\n \"en\": \"Subcategory\",\n \"ar\": \"\"\n },\n \"description\": \"All the breakfast items\",\n \"description_localized\": {\n \"en\": \"All breakfast items\",\n \"ar\": \"\"\n },\n \"preparation_time\": 20,\n \"operational_hours\": [\n {\n \"shifts\": [\n {\n \"start_time\": \"10:00\",\n \"end_time\": \"12:00\"\n }\n ],\n \"active\": true,\n \"day_of_week\": 5\n }\n ],\n \"items\": [\n \"pancakes\",\n \"shawarma\"\n ]\n }\n ],\n \"items\": [\n {\n \"id\": \"pancakes\",\n \"name\": \"Pancakes\",\n \"name_localized\": {\n \"en\": \"Pancakes\",\n \"ar\": \"\"\n },\n \"description\": \"Fresh egg and chocolate pancakes\",\n \"description_localized\": {\n \"en\": \"Fresh egg and chocolate pancakes\",\n \"ar\": \"\"\n },\n \"active\": true,\n \"price\": 20,\n \"calorie_counts\": \"200\",\n \"allergic_information\": \"allergic to eggs\",\n \"operational_hours\": [\n {\n \"shifts\": [\n {\n \"start_time\": \"10:00\",\n \"end_time\": \"12:00\"\n }\n ],\n \"active\": true,\n \"day_of_week\": 5\n }\n ],\n \"media\": \"https://picsum.photos/300.jpg\",\n \"groups\": [\n \"sauces\"\n ]\n },\n {\n \"id\": \"shawarma\",\n \"deleted\": true\n }\n ],\n \"groups\": [\n {\n \"id\": \"sauces\",\n \"name\": \"Choose sauce\",\n \"name_localized\": {\n \"en\": \"Choose sauce\",\n \"ar\": \"\"\n },\n \"description\": \"Sauce for your main dish\",\n \"description_localized\": {\n \"en\": \"Sauce for dressing\",\n \"ar\": \"\"\n },\n \"min\": 1,\n \"max\": 1,\n \"options\": [\n \"barbecue\",\n \"soy\"\n ]\n }\n ],\n \"options\": [\n {\n \"id\": \"barbecue\",\n \"deleted\": true\n },\n {\n \"id\": \"soy\",\n \"name\": \"Soy sauce\",\n \"name_localized\": {\n \"en\": \"Soy sauce\",\n \"ar\": \"\"\n },\n \"active\": true,\n \"price\": 20\n }\n ]\n}\n```\n
\n\n# Update a group\n\n**Example for updating a group using diff = true**\n\n
\nExpand to see the payload\n\n```json\n{\n \"diff\": true,\n \"catalog\": {\n \"id\": \"DefaultCatalog\",\n \"category_ids\": [\n \"breakfast\"\n ]\n },\n \"categories\": [\n {\n \"id\": \"breakfast\",\n \"items\": [\n \"pancakes\"\n ]\n }\n ],\n \"items\": [\n {\n \"id\": \"pancakes\",\n \"active\": true,\n \"groups\": [\n \"syrups\"\n ]\n }\n ],\n \"groups\": [\n {\n \"id\": \"syrups\",\n \"min\": 0,\n \"max\": 2\n }\n ],\n \"options\": []\n}\n```\n
\n\n# Update an option\n\n**Example for updating an option using diff = true**\n\n
\nExpand to see the payload\n\n```json\n{\n \"diff\": true,\n \"catalog\": {\n \"id\": \"DefaultCatalog\",\n \"category_ids\": [\n \"breakfast\"\n ]\n },\n \"categories\": [\n {\n \"id\": \"breakfast\",\n \"items\": [\n \"pancakes\"\n ]\n }\n ],\n \"items\": [\n {\n \"id\": \"pancakes\",\n \"active\": true,\n \"groups\": [\n \"syrups\"\n ]\n }\n ],\n \"groups\": [\n {\n \"id\": \"syrups\",\n \"options\": [\n \"maple\"\n ]\n }\n ],\n \"options\": [\n {\n \"id\": \"maple\",\n \"price\": 5\n }\n ]\n}\n```\n
\n\n# Update an item\n\n**Example for updating an item using diff = true**\n\n
\nExpand to see the payload\n\n```json\n{\n \"diff\": true,\n \"catalog\": {\n \"id\": \"DefaultCatalog\",\n \"category_ids\": [\n \"breakfast\"\n ]\n },\n \"categories\": [\n {\n \"id\": \"breakfast\",\n \"items\": [\n \"pancakes\"\n ]\n }\n ],\n \"items\": [\n {\n \"id\": \"pancakes\",\n \"active\": true\n }\n ],\n \"groups\": [],\n \"options\": []\n}\n```\n
\n\n# Delete an item\n\n**Example for deleting an item using diff = true**\n\n
\nExpand to see the payload\n\n```json\n{\n \"diff\": true,\n \"catalog\": {\n \"id\": \"DefaultCatalog\",\n \"category_ids\": [\n \"breakfast\"\n ]\n },\n \"categories\": [\n {\n \"id\": \"breakfast\",\n \"items\": [\n \"pancakes\"\n ]\n }\n ],\n \"items\": [\n {\n \"id\": \"pancakes\",\n \"deleted\": true\n }\n ],\n \"groups\": [],\n \"options\": []\n}\n```\n
\n\n**Sending all fields empty as follows would not mean deleting a catalog. This type of payload will be discarded as bad request.**\n\n
\nExpand to see the payload\n\n```json\n{\n \"diff\": true,\n \"catalog\": {},\n \"categories\": [],\n \"items\": [],\n \"groups\": [],\n \"options\": []\n}\n```\n
", "x-displayName": "Sample requests" }, { "name": "Order API overview", "description": "The **Order API** allows partners to retrieve and manage orders. The API also includes sending order notifications to a partner's webhook.", "x-displayName": "Overview" }, { "name": "Order API components", "description": "- **List orders**\n - To access branch orders, use the GET /orders endpoint.\n- **Fetch order details**\n - To fetch an order's details by its ID, use the GET /orders/{order_id} endpoint.\n- **Accept/cancel order**\n - To accept/cancel an order, use the PUT /orders/{order_id} endpoint.\n- **Mark order as ready**\n - To mark an order as ready for pickup, use the PUT /orders/{order_id} endpoint.\n- **Tag orders**\n - Tag an order with your own metadata via the PATCH /orders/{order_id}/tags endpoint.\n- **Receive order notifications**\n - The order API would send notifications to your webhook as an order progresses through different states.", "x-displayName": "Components" }, { "name": "Order API endpoints", "description": "This section covers endpoints for the order API.", "x-displayName": "Endpoints" }, { "name": "Order API webhook events", "description": "The API supports the following webhook events:\n\n| Event | Trigger |\n|----------------------|-----------------------------------|\n| ORDER_CREATED | Customer has placed an order |\n| ORDER_STATUS_UPDATED | Order has advanced to a new state |", "x-displayName": "Webhook events" }, { "name": "Order API flows", "description": "This section covers flows for the order API.\n\n# Order placement\n\n```mermaid\nsequenceDiagram\n actor Customer\n participant Careem SuperApp\n participant Client\n participant Client webhook\n participant Order API\n Customer->>Careem SuperApp: Customer places an order\n Careem SuperApp->>Order API: Receives the order with all details\n Order API-->>Client webhook: Sends an ORDER_CREATED event with status set as pending\n\n alt Partner accepts order\n Client->>Order API: Accepts the order via the PUT /orders/{order_id} endpoint\n Order API-->>Customer: Notify the customer that the order is being prepared\n Order API-->>Client webhook: Sends an ORDER_STATUS_UPDATED event with status set as accepted\n end\n\n alt Partner cancels order\n Client->Order API: Cancels the order via the PUT /orders/{order_id} endpoint\n Order API-->>Customer: Notify the customer that the order has been cancelled\n Order API-->>Client webhook: Sends an ORDER_STATUS_UPDATED event with status set as cancelled\n end\n\n opt Customer cancels order\n Customer->>Careem SuperApp: Customer cancels the order\n Careem SuperApp->>Order API: Cancel the order\n Order API-->>Customer: Notify the customer that the order has been cancelled\n Order API-->>Client webhook: Sends an ORDER_STATUS_UPDATED event with status set as cancelled\n end\n```", "x-displayName": "Flows" }, { "name": "Order API pricing components", "description": "This section covers pricing components of an order.\n\n# 1. Taxes\n\nTax is a percentage that is applied on the order total price.\n\n# 2. Promotion Discounts\n\nThis is the first kind of discounts, and it is a percentage-based discount that is shared between Merchant and Careem. The discount is then applied to the total price of the order after taxes. It consists of two types:\n\n1. `MerchantPromotion` is the discount amount (after calculating the percentage) that the Merchant provides to its customers\n2. `CareemPromotion` is the discount amount (after calculating the percentage) that Careem provides to its customers\n\n**Example:** The merchant has made the decision to offer a promotion discount of 10 AED. This decision was made after agreeing that Careem would contribute to 60% of the discount and the merchant would contribute to 40% of the discount. Therefore, `MerchantPromotion` is 4 AED and `CareemPromotion` is 6 AED.\n\n# 3. Promo Code Discounts\n\nThis is the second kind of discounts, and it is the discount that is applied to specific orders which has a promo code applied by the customer on order check out. Promo code discount can be either percentage or fixed amount. Both Careem and Merchants can have different contributions in the same promo code discount.\n\n**Example:** Promo Code `\"FOODIE\"` can give a fixed discount amount of 10 AED on the total order value. Careem contributes 60% and the merchant contributes 40% to the discount. So, Careem discount amount in this value is 6 AED and the merchant discount amount is 4 AED.\n\n# 4. Delivery Fee\n\nDelivery fee is a fixed amount that is added to the total price after calculating taxes and discounts.\n\n# 5. Service Fee\n\nService fee is the customer fee which Careem collects from customers for overall service providing to customers from ordering to delivery. Service fee is collected on all orders and with all customers except for if there's a specific promo configured.", "x-displayName": "Pricing components" }, { "name": "Order API calculations", "description": "The standard formula for calculating total order price has been specified in the following:\n```text\n$total_taxable_price = $sub_total_price + $delivery_fee + $service_fee\n```\n\nThe delivery fee and service fee are quite straightforward. The following section focuses on the sub-total price.\n\n# Sub-total price\n\nTo compute the sub-total price, you should perform the following steps:\n\n## 1. Compute original/basket price\n\nThis is computed by summing up the original prices of all items along with their options (without discounts).\n```text\n$original_total_price = sum($items_original_prices) + sum($options_original_prices)\n```\n\n## 2. Applying taxes if they exist\n\nThe tax is then applied to the original/basket price by multiplying the tax rate. Please note that this step must be ignored if the tax is zero.\n\n```text\n$sub_total_price_after_taxes = $original_total_price + ($original_total_price * tax_percentage) / 100\n```\n\n## 3. Applying the total promotion discount\n\nThe total promotion discount is computed by adding Merchant's and Careem's contribution to the discount.\n\n```text\n$total_promotion_discount = $merchant_discount_amount + $careem_discount_amount\n```\n\nIt is then applied to the taxed price in the following manner:\n```text\n$sub_total_price_after_taxes_and_promotions = $sub_total_price_after_taxes - $total_promotion_discount\n```\n\n## 4. Applying the promocode discount\n\nThe total promocode discount is computed by adding Merchant's and Careem's contribution to the promocode.\n\n```text\n$total_promocode_discount = $merchant_promo_amount + $careem_promo_amount\n```\n\nIt is then applied to the price computed in the above step in the following manner:\n```text\n$sub_total_price = $sub_total_price_after_taxes_and_promotions - $total_promocode_discount\n```\n\nWe can conclude this section as it represents the final step, where we have successfully computed the sub-total price.\n\n# Example\n\nBelow is a sample request payload for an order:\n
\nExpand to see the payload\n\n```json\n{\n \"details\": {\n \"id\": 100482992,\n \"items\": [\n {\n \"id\": \"UlVXLKDuEZ7tzQXxirYKYR0ZfOo\",\n \"notes\": \"test order\",\n \"groups\": [\n {\n \"id\": \"I6YEPYTHjSAgMULUg5GXffZrPb4\",\n \"options\": [\n {\n \"id\": \"2AbV6ggS8D6z234dCPz0CJ4Psyo\",\n \"quantity\": 1,\n \"total_price\": 2.62\n }\n ]\n },\n {\n \"id\": \"aLhJmZGI7ZbdS87TMr7I0cDgfh4\",\n \"options\": [\n {\n \"id\": \"qkw-ui3UpUN6fhRBWFQGSCafnSo\",\n \"quantity\": 1,\n \"total_price\": 1.05\n },\n {\n \"id\": \"RKv1Bd-xp0i0jg0t_idGtcpdpGI\",\n \"quantity\": 1,\n \"total_price\": 1.05\n },\n {\n \"id\": \"T7jJ2ZEZscDgbrwr2h-H5lp2PEA\",\n \"quantity\": 1,\n \"total_price\": 3.15\n },\n {\n \"id\": \"4ioxDxPENssFA23turt4iYadaXY\",\n \"quantity\": 1,\n \"total_price\": 2.1\n }\n ]\n },\n {\n \"id\": \"i1gSIXvpL3j9kCcjWUaabiWQz1I\",\n \"options\": [\n {\n \"id\": \"2KwZqe00QIDAQsvRi6si3Em3PmE\",\n \"quantity\": 1,\n \"total_price\": 1.05\n },\n {\n \"id\": \"lXHz6kvIpDEp8D2EtuB3EagYLgo\",\n \"quantity\": 1,\n \"total_price\": 3.15\n },\n {\n \"id\": \"2H7lPx-NILSNp6-3IzpoH6G4lSo\",\n \"quantity\": 1,\n \"total_price\": 5.25\n },\n {\n \"id\": \"FsUtWkstyiUIkwVvDwV0KEEoSIA\",\n \"quantity\": 1,\n \"total_price\": 5.25\n }\n ]\n }\n ],\n \"quantity\": 1,\n \"unit_price\": 10.5,\n \"item_price\": 10.5,\n \"total_price\": 35.17\n },\n {\n \"id\": \"6ivLhXFVQqpXXyqrN_HIsaXdQTw\",\n \"notes\": \"\",\n \"groups\": [],\n \"discount\": 4.2,\n \"quantity\": 2,\n \"unit_price\": 5.25,\n \"item_price\": 10.5,\n \"total_price\": 10.5\n }\n ],\n \"notes\": \"\",\n \"price\": {\n \"promo_code\": \"\",\n \"delivery_fee\": 7,\n \"free_delivery_discount_value\": 0,\n \"service_fee\": 1,\n \"tax_percentage\": 0,\n \"total_taxable_price\": 35.4,\n \"original_total_price\": 46.67,\n \"merchant_promo_amount\": 0,\n \"careem_promo_amount\": 0,\n \"merchant_discount_amount\": 18.27,\n \"careem_discount_amount\": 0\n },\n \"branch\": {\n \"id\": \"a5677341-8p06-4bf8-7b95-aaf42513569a\",\n \"name\": \"Example Branch\",\n \"state\": \"MAPPED\",\n \"created_at\": \"2020-10-28T15:05:48Z\",\n \"updated_at\": \"2020-11-04T08:51:01Z\"\n },\n \"status\": \"pending\",\n \"captain\": {\n \"name\": \"\",\n \"phone_number\": \"\"\n },\n \"cash_in\": 0,\n \"customer\": {\n \"name\": \"\",\n \"address\": {\n \"area\": \"\",\n \"city\": \"\",\n \"name\": \"\",\n \"note\": \"\",\n \"number\": \"\",\n \"street\": \"\",\n \"building\": \"\",\n \"location\": {\n \"lat\": \"\",\n \"lng\": \"\"\n }\n },\n \"payment_type\": \"\",\n \"phone_number\": 0\n },\n \"created_at\": \"2020-11-25T08:57:35Z\",\n \"delivery_type\": \"careem\",\n \"merchant_pay_type\": \"\",\n \"cancellation_reason\": \"\"\n },\n \"event_type\": \"ORDER_CREATED\"\n}\n```\n
\n\n## Givens\n\n- **Taxes:** 0%\n- **Merchant Promotion:** 18.27\n- **Careem Promotion:** 0\n- **Promo Code:** no promo code (Merchant contribution and Careem contribution are zero)\n- **Delivery Fee:** 7\n- **Service Fee:** 1\n\n## Calculations\n\n### 1. Calculate original/basket price\n\n```text\n$original_total_price = sum($items_original_prices) + sum($options_original_prices)\n\n$item1_price = 10.5\n$item2_price = 10.5\nsum($items_original_prices) = $item1_price + $item2_price = 10.5 + 10.5 = 21\n\n$item1_options_prices = 2.62 + 1.05 + 1.05 + 3.15 + 2.1 + 1.05 + 3.15 + 5.25 + 5.25 = 24.67\n$item2_options_prices = 0\nsum($options_original_prices) = $item1_options_prices + $item2_options_prices = 24.67 + 0 = 24.67\n\nLet's plug in the values:\n$original_total_price = 21 + 24.67 = 45.67\n```\n\n### 2. Apply tax\n\n```text\n$sub_total_price_after_taxes = $original_total_price + ($original_total_price * tax_percentage) / 100\n\n$original_total_price = 45.67\n$tax_percentage = 0\n\nLet's plug in the values:\n$sub_total_price_after_taxes = 45.67 + (45.67 * 0) / 100 = 45.67 + 0 = 45.67\n```\n\n### 3. Apply total promotion discount\n\n```text\n$total_promotion_discount = $merchant_discount_amount + $careem_discount_amount\n\n$merchant_discount_amount = 18.27\n$careem_discount_amount = 0\n\nLet's plug in the values to compute the total promotion discount:\n$total_promotion_discount = 18.27 + 0 = 18.27\n\nHence,\n$sub_total_price_after_taxes_and_promotions = $sub_total_price_after_taxes - $total_promotion_discount\n$sub_total_price_after_taxes_and_promotions = 45.67 - 18.27 = 27.40\n```\n\n### 4. Apply promocode discount\n\n```text\n$total_promocode_discount = $merchant_promo_amount + $careem_promo_amount\n\n$merchant_promo_amount = 0\n$careem_promo_amount = 0\n\nLet's plug in the values to compute the total promocode discount:\n$total_promocode_discount = 0 + 0 = 0\n\nHence,\n$sub_total_price = $sub_total_price_after_taxes_and_promotions - $total_promocode_discount\n$sub_total_price = 27.40 - 0 = 27.40\n```\n\n### 5. Add delivery fee & service fee\n\n```text\n$total_taxable_price = $sub_total_price + $delivery_fee + $service_fee\n\n$sub_total_price = 27.40\n$delivery_fee = 7\n$service_fee = 1\n\nLet's plug in the values to get the total price:\n$total_taxable_price = 27.40 + 7 + 1 = 35.4\n```\n\n\n# Order calculator\n\nYou can utilize the provided calculator to observe the appearance of the pricing component within the webhook payload. It is pre-filled with the data from the above example.\n\n
\nExpand to view the calculator\n\n
\n\n
\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
\n\n
\n\n\n
\n", "x-displayName": "Calculating totals" }, { "name": "FAQs & Troubleshooting", "description": "This section covers commonly asked questions and issues that partners may encounter while using our API. If you have any questions or issues, feel free to contact us. We will do our best to assist you.\n\n# API\n\n**Question: I received the following API error. How should I resolve it?**\n```json\n{\n \"message\": \"clients not found for client_id=\",\n \"code\": \"NOT_FOUND_ERROR\",\n \"error_type\": \"NotFoundError\",\n \"errors\": null\n}\n```\n\nBefore consuming our APIs, a webhook URL must be configured for the said environment. Please provide the webhook URL and the associated secret to the engineering team in order to resolve this issue.\n\n**Question: I received the following API error. How should I resolve it?**\n\n```json\n{\n \"message\": \"Validation Error\",\n \"code\": \"VALIDATION_ERROR\",\n \"error_type\": \"ValidationError\",\n \"errors\": [\n {\n \"errors\": [\n {\n \"message\": \"Name cannot be blank!\"\n },\n {\n \"message\": \"Name cannot be blank!\"\n },\n {\n \"message\": \"Name cannot be blank!\"\n }\n ],\n \"field\": \"Name\"\n }\n ]\n}\n```\n\nPlease ensure entities such as brands, branches, catalogs, categories, items, groups and options have valid non-blank names in your request.\n\n**Question: I received the following API error. How should I resolve it?**\n\n```json\n{\n \"message\": \"Validation Error\",\n \"code\": \"VALIDATION_ERROR\",\n \"error_type\": \"ValidationError\",\n \"errors\": [\n {\n \"errors\": [\n {\n \"message\": \"branch_id is not mapped\"\n }\n ],\n \"field\": \"branch_id\"\n }\n ]\n}\n```\n\nThis happens when a branch is not mapped. This is a necessary step for onboarding the branch to SuperApp. Please reach out to the operations team to help you out with the mapping.\n\n**Question: I received the following API error. How should I resolve it?**\n\n```json\n{\n \"message\": \"Forbidden Error\",\n \"code\": \"FORBIDDEN_ERROR\",\n \"error_type\": \"ForbiddenError\",\n \"errors\": [\n {\n \"reason\": \"Catalog cannot be reset for a branch with catalog creation in progress. Please wait until the job has ended.\"\n }\n ]\n}\n```\n\nPlease wait for the catalog to be processed on our end. If the processing doesn't complete within 30 minutes, please reach out to the engineering team.\n\n**Question: I received the following error from the catalog reset API. How should I resolve it?**\n\n```json\n{\n \"message\": \"Api deprecated Error\",\n \"code\": \"API_DEPRECATED_ERROR\",\n \"error_type\": \"APIDeprecatedError\",\n \"errors\": null\n}\n```\n\nThis endpoint has been deprecated since 24th April 2024. Instead of catalog resets, we recommend all our partners to use the PUT /catalogs endpoint for catalog updates.\n\nHowever, at the same time, you may request an approval for consuming the endpoint from your system.\n\n**Question: I received a 401 error from the API. How should I resolve it?**\n\n401 is returned when a valid token is not supplied with the request. Make sure that you've provided a valid token in your request. Please refer to the [authentication section](#tag/Auth-overview) for more details.\n\n**Question: I received a 429 error from the API. How should I resolve it?**\n\n429 means that you are being rate-limited due to a high number of requests. Please refer to the [Rate limiting section](#section/Getting-started/Rate-limiting) for more details.\n\n\n# Webhook events\n\n**Question: We have not received any order notification updates from Careem. How should I resolve this issue?**\n\nThis may happen if:\n- The branch is not mapped to a Careem outlet. Contact operations team to map the branch.\n- POS integration for the branch is disabled. Use API to enable POS integration.\n- The branch is using Careem's portal to accept orders. Always log out and refrain from using the portal for accepting orders.\n\n**Question: Are there any retries if the partner's webhook returns an HTTP status code other than 200 OK?**\n\nOur API supports up to 4 retries for failed requests to the partner's webhook endpoint, with a maximum of 5 attempts in total, including the initial call.\n\n**Question: Do you send any notification update on the partner's webhook when the branch's status is changed?**\n\nNo. We do not send any such updates to your webhook.\n\n**Question: Why do I not get any customer information back on my webhook?**\n\nCustomer information is ONLY sent for self-delivery orders.\n\n# Branch\n\n**Question: Why is my order getting accepted immediately as soon as I place it?**\n\nThis happens if order auto-acceptance is enabled for your branch. Please reach out to our operations team to disable it.\n\n**Question: Is there any time limit for order acceptance by a branch?**\n\nYes. This is configured by the Operations team.\n\n**Question: The brand state shows as \"UNMAPPED\" while the branch that is created under the brand shows as \"MAPPED\". Is this normal?**\n\nYes, this is fine. The operations team maps branches ONLY, not brands.\n\n**Question: Is the self-delivery model for branches supported by the API?**\n\nYes. Please refer to delivery_type in the order object\n\n**Question: How do I persist my branch's location information?**\n\nThe API does not support any attribute for location. The location of the branch is populated by the operations team during the time of mapping.\n\n**Question: Can Careem-based promotions and partner-based promotions run in parallel?**\n\nYes.\n\n**Question: Is it possible to create discounts via the API?**\n\nCurrently, API does not support the creation of discounts. To process discounts and promotions, we follow the same procedures as we currently have in place. However, in the future, we plan to introduce APIs for these functions as well. The order details will include information on any discounts or partner shared promotions applied to the order, but the configuration of discounts and promotions is not possible through the APIs at this time.\n\n**Question: Is it possible to support item-level discounts?**\n\nNo.\n\n# Catalog\n\n**Question: I received the following as the reason for my catalog failure. How should I resolve this issue?**\n```text\nvalidation error, customization group max must be between group min and number of group options when multiSelect is false\n```\n\nPlease ensure that the group `min`, `max` and `multi_select` fields adhere to the following validation rules:\n\n- When `multi_select` is false:\n - The group `min` must be between 0 and number of group options. (0 <= group `min` <= number of group options)\n - The group `max` must be between the group `min` and number of group options. (group `min` <= group `max` <= number of group options)\n- When `multi_select` is true:\n - The group `min` must be greater than 1. (group `min` > 1)\n - The group `max` must be equal to the group min. (group `max` = Group `min`)\n- Additionally, when the group object has nested groups, setting `multi_select` to true is not allowed.\n\n**Question: What are the languages supported when sending a catalog?**\n\nWe only support Arabic and English at the moment.\n\n**Question: What are the possible currencies?**\n\nPlease refer to the catalog.currency_id attribute in the catalog API response.\n\n**Question: What is the order of precedence for the entire catalog in terms of operational hours?**\n\nCatalog > Category > Sub-category > Item\n\n**Question: Are all the prices of entities defined in the catalog tax-inclusive?**\n\nYes.\n\n**Question: Can you please mention the VAT for KSA & UAE?**\n\nKSA: 15%\n\nUAE: 5%\n\n# Order\n\n**Question: What are the payment methods for captain and customer each?**\n\nRefer to customer.payment_type for customer's payment methods in the order object.\n\nRefer to merchant_pay_type for captain's payment methods in the order object.\n\n**Question: During testing, we found out that the cash_in value is always coming as zero. How to identify the amount that the merchant will be collecting in self-delivery? Also, will it always be zero in case of Careem delivery?**\n\ncash_in is the amount that needs to be collected from customers. If it's 0, you can assume the order is paid. And no, it would not always be 0.\n\n**Question: What is merchant_pay_type?**\n\nmerchant_pay_type field refers to the way payment is exchanged between the merchant (restaurant) and the driver. It can be either \"cash\" or \"prepaid\"\n\n**Question: Is merchant_pay_type of any significance to partners that use Careem delivery?**\n\nFor Careem delivery, merchant_pay_type is irrelevant because Careem collects the payments themselves.\n\nFor self-delivery, partners should look at customer.payment_type. That tells a partner whether it's a prepaid order or cash.\n\n**Question: Are there any tracking capabilities for self-delivery orders? Is it possible for partners to push their order updates to your system?**\n\nNo. There are no tracking capabilities for self-delivery orders. The Careem SuperApp informs the user as such after placing the order.\n\n**Question: Do integrated branches receive orders on the Careem dashboard?**\n\nThe restaurant's access to Careem dashboard will be restricted. They should immediately log out and use our partner's systems. All order statuses for integrated customers should be relayed via the API otherwise this could cause issues.\n\n# SuperApp\n\n**Question: How can I view the existing catalog of my branch?**\n\nUnfortunately, we've deprecated the API endpoint for fetching catalogs. You can view the existing catalog by looking up your branch on SuperApp provided by our engineering team.\n\n**Question: I am unable to find my branch on SuperApp. What could be the reason and how do I fix this?**\n\nPlease make sure that:\n\n- Your location is set close to the branch's location.\n- You've provided the correct name for the branch in the search bar.\n- You've pushed a catalog and it has at least one active item.\n\n**Question: How do I place an order from my branch on SuperApp, given that it is showing closed?**\n\nPlease enable POS integration for the branch via the branch API. If you have already done that, then please confirm the branch's operational hours.\n\nIf the time you choose to place your order falls outside the branch's operational hours, you will not be able to place an order. However, you can change the branch's operational hours via the API if you would like to.\n\n**Question: Why am I not able to see the same name on SuperApp for my branch that I passed to the branch API?**\n\nPlease note that the name you see on SuperApp is decided mutually between you and the operations team. And this name could be different.\n\n**Question: Do you display any calories information on SuperApp?**\n\nNo.\n\n**Question: How much time does it take for the catalog to reflect on SuperApp?**\n\nIt usually takes around 5 minutes." }, { "name": "Release Notes", "description": "This section covers the release notes for the API. For detailed release notes, please refer to [this document](https://docs.google.com/document/d/1JPQ1pKbKJSmZZsLGTBbH8R1JmlhRPeqP-EKqG5PXMVc/edit?usp=sharing).", "x-displayName": "Release Notes" } ], "paths": { "/token": { "post": { "tags": [ "Auth endpoints" ], "servers": [ { "url": "https://identity.careem.com", "description": "production server" }, { "url": "https://identity.qa.careem-engineering.com", "description": "staging server" } ], "summary": "Generate access token", "description": "Use this endpoint to generate an access token.", "operationId": "generateAccessToken", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "required": [ "client_id", "client_secret", "grant_type", "scope" ], "properties": { "client_id": { "type": "string", "description": "The client identifier." }, "client_secret": { "type": "string", "description": "The client secret." }, "grant_type": { "type": "string", "description": "The grant type. Supports `client_credentials` ONLY." }, "scope": { "type": "string", "description": "The scope for the access request. Supports `pos` ONLY." } } } } } }, "responses": { "200": { "description": "Token generated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "access_token": { "type": "string", "description": "The authorization token.", "example": "JSON Web Token" }, "token_type": { "type": "string", "description": "The token's type.", "example": "Bearer" }, "expires_in": { "type": "number", "description": "The token's lifetime in seconds after the issue time.", "example": 86399 }, "scope": { "type": "string", "description": "The token's scope.", "example": "pos" } } } } } }, "401": { "description": "Unauthorized request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "The error type.", "example": "invalid_client" }, "error_description": { "type": "string", "description": "The error description.", "example": "Bad client credentials" } } } } } }, "500": { "description": "Internal server error" } }, "security": [] } }, "/brands": { "get": { "tags": [ "Store API endpoints" ], "summary": "List brands", "description": "Use this endpoint to view all the brands that you've created.", "operationId": "listBrands", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "User-Agent", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "page_number", "in": "query", "description": "The page number required", "schema": { "type": "integer", "minimum": 1, "default": 1, "example": 2 } }, { "name": "page_size", "in": "query", "description": "Number of brands in one page", "schema": { "type": "integer", "minimum": 1, "maximum": 20, "default": 20 } } ], "responses": { "200": { "description": "Brands retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrandList" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "tags": [ "Store API endpoints" ], "summary": "Create a brand", "description": "Use this endpoint to create a brand.", "operationId": "createBrand", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "User-Agent", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateBrandRequest" } } } }, "responses": { "201": { "description": "Brand created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Brand" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Brand with the specified name already exists", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error" } } } }, "/brands/{brand_id}": { "get": { "tags": [ "Store API endpoints" ], "summary": "Fetch a brand", "description": "Use this endpoint to fetch an existing brand by its ID.", "operationId": "fetchBrand", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "User-Agent", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "brand_id", "in": "path", "required": true, "description": "A unique brand ID string provided by vendor or restaurant", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Brand retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Brand" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Brand with the specified ID was not found" }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "put": { "tags": [ "Store API endpoints" ], "summary": "Update a brand", "description": "Use this endpoint to update an existing brand.", "operationId": "updateBrand", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "User-Agent", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "brand_id", "in": "path", "required": true, "description": "A unique brand ID string provided by vendor or restaurant", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateBrandRequest" } } } }, "responses": { "200": { "description": "Brand updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Brand" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Brand with the specified ID was not found" }, "409": { "description": "Brand with the specified name already exists", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "tags": [ "Store API endpoints" ], "summary": "Delete a brand", "description": "Use this endpoint to delete an existing brand by its ID.", "operationId": "deleteBrand", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "User-Agent", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "brand_id", "in": "path", "required": true, "description": "A unique brand ID string provided by vendor or restaurant", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Brand deleted successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteBrandRequest" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Brand with the specified ID was not found" }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/branches": { "get": { "tags": [ "Store API endpoints" ], "summary": "List branches", "description": "Use this endpoint to fetch all branches that you've created.", "operationId": "listBranches", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "User-Agent", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Brand-Id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "page_number", "in": "query", "description": "The page number required", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "page_size", "in": "query", "description": "Number of branches in one page", "schema": { "type": "integer", "minimum": 1, "maximum": 20, "default": 20 } } ], "responses": { "200": { "description": "Branches retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BranchList" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/branches/{branch_id}": { "put": { "tags": [ "Store API endpoints" ], "summary": "Create/update a branch", "description": "Use this endpoint to create/update a branch.\n\nA branch belongs to a brand, and when a branch is created through this API, it is not considered as a real branch in our system.\nHowever, there is a manual process required by our operations team to map the branch to an actual Careem outlet.\nThis process must be completed only once after each new branch is created using this API.\nYou cannot create any catalog for a branch until it has mapped.\n", "operationId": "createOrUpdateBranch", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "User-Agent", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Brand-Id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "branch_id", "in": "path", "required": true, "description": "A unique branch ID string provided by vendor or restaurant", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PutBranchRequest" } } } }, "responses": { "200": { "description": "Branch updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Branch" } } } }, "201": { "description": "Branch created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Branch" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Branch with the specified name already exists", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "get": { "tags": [ "Store API endpoints" ], "summary": "Fetch a branch", "description": "Use this endpoint to fetch an existing branch by its ID.", "operationId": "fetchBranch", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "User-Agent", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Brand-Id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "branch_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Branch retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Branch" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Branch with the specified ID was not found" }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "tags": [ "Store API endpoints" ], "summary": "Delete a branch", "description": "Use this endpoint to delete an existing branch by its ID.", "operationId": "deleteBranch", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "User-Agent", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Brand-Id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "branch_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Branch deleted successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteBranchRequest" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Branch with the specified ID was not found" }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/branches/{branch_id}/status": { "patch": { "tags": [ "Store API endpoints" ], "summary": "Toggle POS integration", "description": "Use this endpoint to enable or disable POS integration for a branch.\n\nBy default, this toggle is disabled when a branch is created.\nThis is to ensure that vendors can verify that the catalog syncs are successful before enabling the POS integration.\nOnce enabled, orders will be processed through the partner's POS system.\nIf the toggle is disabled, orders will not flow through the POS system.\nInstead, they will be processed manually through the branch's tablets.\nHowever, catalog syncs can still be made for the branch, even if the toggle is off.\n", "operationId": "togglePOSIntegration", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "User-Agent", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Brand-Id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "branch_id", "in": "path", "required": true, "description": "A unique branch ID string provided by vendor or restaurant", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateBranchRequest" } } } }, "responses": { "200": { "description": "Branch updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Branch" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/branches/{branch_id}/visibility/status": { "post": { "tags": [ "Store API endpoints" ], "summary": "Update branch status on SuperApp", "description": "Use this endpoint to update a branch's status on SuperApp.\n\nA branch can hold one of following statuses:\n - `Active (1)`: Branch is active on the platform and customers are able to place orders.\n - `Inactive (2)`: Branch is active on the platform but customers would not be able to place orders.\n\nPlease be aware that it may take approximately 5 minutes for the changes to be reflected on the SuperApp.\n", "operationId": "updateBranchStatus", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "User-Agent", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Brand-Id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "branch_id", "in": "path", "required": true, "description": "A unique branch ID string provided by vendor or restaurant", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusRequest" } } } }, "responses": { "204": { "description": "Branch status updated successfully" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Either the brand or branch doesn't exist, or branch is not mapped", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "get": { "tags": [ "Store API endpoints" ], "summary": "Get branch status on SuperApp", "description": "Use this endpoint to read a branch's current visibility status on SuperApp.\n\nThe `status` reflects the latest known outlet state:\n - `active`: branch is live and accepting orders.\n - `inactive`: branch is temporarily not accepting orders and can be reactivated by the partner.\n - `offline`: branch is not accepting orders and can only be reactivated by Careem operations.\n\n`reason` carries the human-readable reason when the branch is not active (otherwise null). `can_reactivate` is null when not applicable (active), true when the partner can self-reactivate (inactive), and false when only Careem ops can (offline).\n", "operationId": "getBranchStatus", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "User-Agent", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Brand-Id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "branch_id", "in": "path", "required": true, "description": "A unique branch ID string provided by vendor or restaurant", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Branch status retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BranchStatusResponse" } } } }, "400": { "description": "Bad request, or branch is not mapped", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Either the brand or branch doesn't exist, or status is not yet available for this branch", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/branches/{branch_id}/visibility/status/expiries": { "post": { "tags": [ "Store API endpoints" ], "summary": "Set branch status for a specified duration on SuperApp", "description": "Use this endpoint to set a branch's status for a specified duration on SuperApp.\n\nIn the event of a busy kitchen or unforeseen circumstances that cause delays in order fulfillment, this API can be a useful solution.\n", "operationId": "setBranchStatusForFixedDuration", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "User-Agent", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Brand-Id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "branch_id", "in": "path", "required": true, "description": "A unique branch ID string provided by vendor or restaurant", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusExpiriesRequest" } } } }, "responses": { "201": { "description": "Branch status expiry created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BranchStatusExpiriesResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Either the brand or branch doesn't exist, or branch is not mapped", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/operational-hours": { "put": { "tags": [ "Store API endpoints" ], "summary": "Set branch operational hours", "description": "Use this endpoint to set a branch's operational hours.", "operationId": "setBranchOperationalHours", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "User-Agent", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Brand-Id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Branch-Id", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VendorOperationalHour" } } } }, "responses": { "201": { "description": "Branch operational hours updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VendorOperationalHour" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "get": { "tags": [ "Store API endpoints" ], "summary": "Fetch branch operational hours", "description": "Use this endpoint to fetch a branch's operational hours.", "operationId": "fetchBranchOperationalHours", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "User-Agent", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Brand-Id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Branch-Id", "in": "header", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Branch operational hours retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VendorOperationalHour" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/catalogs": { "put": { "tags": [ "Catalog API endpoints" ], "summary": "Create/update full catalog", "description": "Use this endpoint to create/update a catalog for a specific branch in one go.\n\nThe user can provide all necessary details and create/update the entire catalog with a single request.\n\nPlease be aware that it may take approximately 5 minutes for the changes to be reflected on the SuperApp.\n", "operationId": "createFullCatalog", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "User-Agent", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Brand-Id", "in": "header", "required": false, "schema": { "type": "string" } }, { "name": "Branch-Id", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/CreateFullCatalogRequest" }, { "$ref": "#/components/schemas/UpdateFullCatalogRequest" } ] } } } }, "responses": { "200": { "description": "Catalog created/updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateFullCatalogStatusResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error" } } }, "delete": { "tags": [ "Catalog API endpoints" ], "summary": "Reset/delete catalog", "deprecated": true, "description": "Use this endpoint to reset/delete catalog for a branch.\n\nThis endpoint is **ONLY** meant to be used in case of data inconsistencies. Here is how you can carry this out in three steps:\n\n1. Use this Delete API to reset/delete the catalog (calling this API will not immediately delete the catalog. Instead, the old catalog will ONLY be deleted when a new catalog request is sent with diff=false).\n2. Push the entire catalog with diff=false.\n3. If a catalog push request is in progress, then delete API would result in a 403 error code.\n", "operationId": "deleteCatalog", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "User-Agent", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Brand-Id", "in": "header", "required": false, "schema": { "type": "string" } }, { "name": "Branch-Id", "in": "header", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Catalog deleted successfully" }, "403": { "description": "Forbidden request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenErrorResponse" } } } }, "500": { "description": "Internal server error" } } } }, "/catalogs/status/{request_id}": { "get": { "tags": [ "Catalog API endpoints" ], "summary": "Fetch catalog upload request status", "description": "Use this endpoint to fetch the status of a catalog upload request by its ID.", "operationId": "fetchCatalogStatus", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "User-Agent", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Brand-Id", "in": "header", "required": false, "schema": { "type": "string" } }, { "name": "Branch-Id", "in": "header", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "request_id", "required": true, "schema": { "type": "string" }, "description": "The request ID string for the catalog uploaded. This is given as response for a create/update catalog request." } ], "responses": { "200": { "description": "Catalog status retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetCatalogStatusResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Catalog with the specified ID was not found" }, "500": { "description": "Internal server error" } } } }, "/catalogs/{catalog_id}/items": { "patch": { "tags": [ "Catalog API endpoints" ], "summary": "Update item(s) availability", "description": "Use this endpoint to update the availability of a single or multiple items (maximum: 40) of a catalog.\n\nPlease be aware that it may take approximately 5 minutes for the changes to be reflected on the SuperApp.\n", "operationId": "updateItemsAvailability", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "User-Agent", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Brand-Id", "in": "header", "required": false, "schema": { "type": "string" } }, { "name": "Branch-Id", "in": "header", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "catalog_id", "required": true, "schema": { "type": "string" }, "description": "A unique catalog ID string provided by vendor or restaurant" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateItemsRequest" } } } }, "responses": { "204": { "description": "Item(s) updated successfully" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Catalog with the specified ID was not found" }, "500": { "description": "Internal server error" } } } }, "/orders": { "get": { "tags": [ "Order API endpoints" ], "summary": "List orders", "description": "Use this endpoint to access branch orders.", "operationId": "listOrders", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "User-Agent", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Brand-Id", "in": "header", "required": false, "schema": { "type": "string" } }, { "name": "Branch-Id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "page_number", "in": "query", "description": "The page number required", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "page_size", "in": "query", "description": "Number of orders in one page", "schema": { "type": "integer", "minimum": 1, "maximum": 20, "default": 20 } }, { "name": "branch_id", "in": "query", "description": "filtering by branch_id", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Orders retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderList" } } } }, "404": { "description": "Order with the specified ID was not found" }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/orders/{order_id}": { "get": { "tags": [ "Order API endpoints" ], "summary": "Fetch order's details by ID", "description": "Use this endpoint to fetch an order's details by its ID.", "operationId": "fetchOrderByID", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "User-Agent", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Brand-Id", "in": "header", "required": false, "schema": { "type": "string" } }, { "name": "Branch-Id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "order_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Order retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Order with the specified ID was not found" }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "put": { "tags": [ "Order API endpoints" ], "summary": "Update order state", "description": "Use this endpoint to accept/cancel an order or mark an order as ready for pickup.\n\n**Unavailable Items**\n\nWhen cancelling an order due to item unavailability (e.g. `ITEM_PERMANENTLY_NOT_AVAILABLE` or `ITEM_TEMPORARILY_UNAVAILABLE`),\nyou can optionally provide the list of unavailable items in the `unavailable_items` field.\n\nThis data is used to drive future decisions such as automatically snoozing items that are temporarily out of stock,\npreventing them from appearing on the menu until they are available again.\n\n**Example request body:**\n```json\n{\n \"state\": \"cancelled\",\n \"cancellation_reason\": \"ITEM_TEMPORARILY_UNAVAILABLE\",\n \"unavailable_items\": [\n {\n \"item_id\": \"item-123\",\n \"item_type\": \"item\"\n },\n {\n \"item_id\": \"modifier-456\",\n \"item_type\": \"modifier_option\"\n }\n ]\n}\n```\n", "operationId": "updateOrder", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "User-Agent", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Brand-Id", "in": "header", "required": false, "schema": { "type": "string" } }, { "name": "Branch-Id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "order_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateOrderRequest" } } } }, "responses": { "200": { "description": "Order state updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelledOrder" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Order with the specified ID was not found" }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/orders/{order_id}/delay-request": { "put": { "tags": [ "Order API endpoints" ], "summary": "Request more preparation time", "description": "Use this endpoint to ask for more preparation time for an order. Only one request is permitted per order.", "operationId": "delayRequestForOrder", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "User-Agent", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Brand-Id", "in": "header", "required": false, "schema": { "type": "string" } }, { "name": "Branch-Id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "order_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderDelayRequest" } } } }, "responses": { "200": { "description": "Order delay updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderDelaySuccessResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderDelayFailureResponse" } } } }, "404": { "description": "Order with the specified ID was not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/orders/{order_id}/tags": { "patch": { "tags": [ "Order API endpoints" ], "summary": "Tag order with metadata", "description": "Use this endpoint to attach metadata to an order.", "operationId": "tagOrder", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "User-Agent", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Brand-Id", "in": "header", "required": false, "schema": { "type": "string" } }, { "name": "Branch-Id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "order_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TagOrderRequest" } } } }, "responses": { "204": { "description": "Order tagged successfully" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Order with the specified ID was not found" }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } } }, "x-webhooks": { "CatalogRequestStatusUpdateNotification": { "post": { "tags": [ "Catalog API webhook events" ], "summary": "CATALOG_REQUEST_STATUS_UPDATED", "operationId": "SendCatalogRequestStatusUpdateNotification", "description": "This notification is sent to the partner's webhook endpoint to indicate that a catalog request has been processed.\nNote- Warnings may be included in the details if there are non-blocking issues with the catalog request. For example, for an item if mandatory option groups are ranked after optional groups.\nwarnings contain following information\n- `entity_name` Name of the entity (category/item) that has the warning\n- `entity_id` ID of the entity (category/item) that has the warning\n- `entity_type` Type of the entity (CATEGORY/PRODUCT)\n- `level` Level of the warning (Item/Category/Add-on group/Item)\n- `severity` Severity of the warning (LOW/MEDIUM/HIGH)\n- `description` Description of the warning\n- `ticket_created_at` Time RFC3339 format in UTC when the warning ticket was created\n- `entity_updated_at` Time RFC3339 format in UTC when the entity was last updated", "requestBody": { "content": { "application/json": { "example": { "event_id": "50ef5753-1825-4774-91f5-afd5f2fbabf0", "event_type": "CATALOG_REQUEST_STATUS_UPDATED", "details": { "status": "COMPLETED", "catalog_id": "602869", "request_id": 9294432, "vendor_brand_id": "893426", "vendor_branch_id": "602869", "warnings": [ { "entity_name": "Ranch Meal For Two", "entity_id": "12345", "entity_type": "PRODUCT", "level": "item", "severity": "LOW", "description": "Mandatory option groups are ranked after optional groups. Please fix the sorting", "ticket_created_at": "2023-03-24T13:20:13Z", "entity_updated_at": "2023-03-20T10:15:30Z" } ] }, "occurred_at": "2023-03-24T13:20:13Z" } } } }, "responses": { "2XX": { "description": "Return any 2XX status to indicate that the data was received successfully" } }, "security": [] } }, "OrderCreationNotification": { "post": { "tags": [ "Order API webhook events" ], "summary": "ORDER_CREATED", "operationId": "SendOrderCreationNotification", "description": "This notification is sent to the partner's webhook endpoint to indicate that a customer has placed an order on SuperApp.\n\nNote: For scheduled orders, the value of `captain.eta` reflects the estimated time of arrival based on the customer's selected delivery time slot. \n\nThe `delivery` field will include slot information exclusively for scheduled orders, providing details about the chosen time window.\n\nThe `Customer - segment` field indicates which segment a customer belongs to, based on their order history. This field can have one of the following values:\n\n- New Customer:\n ```json\n \"segments\": [\n {\n \"ar\": \"زبون جديد\",\n \"en\": \"New Customer\"\n }\n ]\n ```\n- Repeat Customer:\n ```json\n \"segments\": [\n {\n \"ar\": \"زبون متكرر، ٢–٤ طلبات\",\n \"en\": \"Repeat Customer (2-4 Orders)\"\n }\n ]\n ```\n- High Value Customer\n ```json\n \"segments\": [\n {\n \"ar\": \"عميل ذو قيمة عالية، أكثر من ٥ طلبات\",\n \"en\": \"High Value Customer (5+ Orders)\"\n }\n ]\n ```\n", "requestBody": { "content": { "application/json": { "example": { "event_type": "ORDER_CREATED", "details": { "id": 62504546, "status": "pending", "branch": { "name": "Subway", "id": "5f915a5a-1d24-4101-ba8c-f4e5f00703bf", "brand_id": "bddd1d9f-3839-4186-9f10-33b46047c846", "state": "MAPPED", "created_at": "2023-06-07T07:57:12Z", "updated_at": "2023-06-13T11:28:05Z", "active": true, "catalog_id": null }, "merchant_pay_type": "prepaid", "delivery_type": "careem", "delivery": { "type": "careem", "delivery_mode": "scheduled", "schedule_detail": { "time_slot": { "start": "2025-05-01T09:00:00Z", "end": "2025-05-01T09:00:00Z" } } }, "notes": "", "price": { "service_fee": 3.8, "delivery_fee": 7.5, "tax_percentage": 0, "careem_promo_amount": 0, "total_taxable_price": 77.8, "original_total_price": 95, "merchant_promo_amount": 0, "careem_discount_amount": 0, "merchant_discount_amount": 28.5, "free_delivery_discount_value": 0 }, "customer": { "name": "", "address": { "area": "", "city": "", "name": "", "note": "", "number": "", "street": "", "building": "", "location": { "lat": "", "lng": "" } }, "segments": [ { "ar": "عميل ذو قيمة عالية، أكثر من ٥ طلبات", "en": "High Value Customer (5+ Orders)" } ], "payment_type": "", "phone_number": 0 }, "captain": { "name": "", "phone_number": "", "eta": "2024-09-01T15:01:32.895Z" }, "cash_in": 0, "items": [ { "id": "d92fdf11-f4a2-4ce3-8fbe-fc658bfbed5a", "event": null, "notes": "", "groups": [ { "id": "d92fdf11-f4a2-4ced-8fade-fc65adbed5a", "options": [ { "id": "d92f11-fa2-4ce3-8fbe-fadafd", "quantity": 1, "discount": 1, "careem_discount_amount": 0, "merchant_discount_amount": 1, "total_price": 1 } ] } ], "quantity": 1, "delta_quantity": 0, "discount": 2.3, "careem_discount_amount": 0, "merchant_discount_amount": 2.3, "item_price": 11, "unit_price": 11, "total_price": 11, "tags": [ "careem-mealson" ] }, { "id": "f773fe1b-ba1e-41a3-8d84-5fc7e2d8fb9f", "event": null, "notes": "", "groups": [], "quantity": 1, "discount": 3.3, "careem_discount_amount": 0, "merchant_discount_amount": 3.3, "item_price": 11, "unit_price": 11, "total_price": 11, "delta_quantity": 0, "tags": [ "careem-mealson" ] }, { "id": "00fdaac1-3406-4466-9093-f90539bff903", "event": null, "notes": "", "groups": [], "quantity": 1, "discount": 4.8, "careem_discount_amount": 0, "merchant_discount_amount": 4.8, "item_price": 16, "unit_price": 16, "total_price": 16, "delta_quantity": 0, "tags": [ "careem-mealson" ] }, { "id": "1689aec4-5b30-43fe-a23e-52368d1f2ae6", "event": null, "notes": "", "groups": [], "quantity": 1, "discount": 4.8, "careem_discount_amount": 0, "merchant_discount_amount": 4.8, "item_price": 16, "unit_price": 16, "total_price": 16, "delta_quantity": 0 }, { "id": "6552fee1-810b-43a3-9304-c490892c25f9", "event": null, "notes": "", "groups": [], "quantity": 1, "discount": 12.3, "careem_discount_amount": 0, "merchant_discount_amount": 12.3, "item_price": 41, "unit_price": 41, "total_price": 41, "delta_quantity": 0 } ], "cancellation_reason": "", "created_at": "2024-07-25T14:57:20Z", "is_scheduled": false, "updated_at": null, "metadata": { "order_instructions": { "merchant_notes": "text field for merchant notes", "merchant_instructions": [ { "label": "INCLUDE_CUTLERY", "icon_url": "test.url", "name_localized": { "en": "Include Cutlery", "ar": "أدوات المائدة متضمنة" } } ] }, "tags": [ "careem-mealson" ] } } } } } }, "responses": { "2XX": { "description": "Return any 2XX status to indicate that the data was received successfully" } }, "security": [] } }, "OrderStatusUpdateNotification": { "post": { "tags": [ "Order API webhook events" ], "summary": "ORDER_STATUS_UPDATED", "operationId": "SendOrderStatusUpdateNotification", "description": "This notification is sent to the partner's webhook endpoint to indicate that an order has advanced to a new state.\n\nAll order states have been specified below:\n\n| State | Explanation |\n|---------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| accepted | The order is now accepted by the branch and is being prepared. |\n| slot_upcoming | For `scheduled orders`, this state is triggered a configurable number of minutes before the scheduled delivery slot begins. Partners can use this event to prepare for upcoming orders. |\n| slot_started | For `scheduled orders`, this state is triggered at the exact start time of the scheduled delivery slot. Partners can use this event to begin preparing the order for pickup or delivery. |\n| driver_coming | When the captain has been assigned to the order and is on their way to the pickup location. The captain's details will be filled in the `captain` field of the order. |\n| driver_here | The captain has arrived at the pickup location and is ready to pick up the order. |\n| trip_started | When the captain has picked up the order and is on their way to the drop-off location. |\n| trip_ended | The order has been successfully delivered to the customer. |\n| cancelled | The order has been cancelled, and the reason for cancellation will be recorded in the `cancellation_reason` field of the order. |\n\nNote: The key `pickup_time` will only be available when the order's state is in either `driver_coming` or `trip_started`.\n\nThe `delivery.delivery_mode` and `delivery.schedule_detail` fields are present only for scheduled orders, and will include the selected time slot information.\n", "requestBody": { "content": { "application/json": { "example": { "event_type": "ORDER_STATUS_UPDATED", "details": { "id": 62503433, "status": "accepted", "branch": { "name": "Subway", "id": "5f915a5a-1d24-4101-ba8c-f4e5f00703bf", "brand_id": "bddd1d9f-3839-4186-9f10-33b46047c846", "state": "MAPPED", "created_at": "2023-06-07T07:57:12Z", "updated_at": "2023-06-13T11:28:05Z", "active": true, "catalog_id": null }, "merchant_pay_type": "prepaid", "delivery_type": "careem", "delivery": { "type": "careem", "delivery_mode": "scheduled", "schedule_detail": { "time_slot": { "start": "2025-05-01T09:00:00Z", "end": "2025-05-01T09:00:00Z" } } }, "notes": "", "price": { "original_total_price": 4.7, "merchant_discount_amount": 2.3, "careem_discount_amount": 0, "free_delivery_discount_value": 0, "merchant_promo_amount": 0, "careem_promo_amount": 0, "tax_percentage": 0, "total_taxable_price": 4.4, "delivery_fee": 2, "service_fee": 0.15 }, "customer": { "name": "", "phone_number": 0, "address": { "name": "", "number": "", "location": { "lat": "", "lng": "" }, "building": "", "street": "", "area": "", "city": "", "note": "" }, "payment_type": "" }, "captain": { "name": "", "phone_number": "" }, "cash_in": 0, "items": [ { "id": "00ccc1db-c3b1-40c3-9dbd-eeea83c3db2d", "quantity": 2, "delta_quantity": 0, "event": null, "notes": "Please don't ring the door bell", "unit_price": 1.95, "item_price": 3.9, "total_price": 4.7, "discount": 0, "careem_discount_amount": 0, "merchant_discount_amount": 0, "tags": [ "careem-mealson" ], "groups": [ { "id": "fc47dca5-d6b1-411f-9434-885fcf22d74e", "options": [ { "id": "8c7102d7-1e7d-4790-8fde-8ff49c20f1bc", "quantity": 2, "discount": 0, "careem_discount_amount": 0, "merchant_discount_amount": 0, "total_price": 0.4 } ] } ] } ], "cancellation_reason": "", "created_at": "2023-06-18T22:30:29Z", "is_scheduled": false, "pickup_time": "2023-06-18T22:50:29Z", "updated_at": null, "metadata": { "order_instructions": { "merchant_notes": "text field for merchant notes", "merchant_instructions": [ { "label": "INCLUDE_CUTLERY", "icon_url": "test.url", "name_localized": { "en": "Include Cutlery", "ar": "أدوات المائدة متضمنة" } } ] }, "tags": [ "careem-mealson" ] } } } } } }, "responses": { "2XX": { "description": "Return any 2XX status to indicate that the data was received successfully" } }, "security": [] } }, "OrderItemreplacementAcceptedNotification": { "post": { "tags": [ "Order API webhook events" ], "summary": "ORDER_ITEM_REPLACEMENT_ACCEPTED", "operationId": "SendOrderItemReplacementAcceptedNotification", "description": "This notification is sent to the partner's webhook endpoint to indicate that an item replacement request has been accepted by the customer.\n\nmodified item contains the `event` field with value `deleted` to indicate that the item has been removed from the order and `delta_quantity` field to indicate the number of items removed.\n\nNote: At present event is available for `shops` only, and need merchant to suggest item replacement through careem's merchants portal/app.\n", "requestBody": { "content": { "application/json": { "example": { "details": { "id": 124066159, "items": [ { "id": "", "upc": "upc", "event": "deleted", "notes": "", "groups": [ { "id": "", "options": [ { "id": "", "upc": "upc", "discount": 0, "quantity": 2, "total_price": 0, "careem_discount_amount": 0, "merchant_discount_amount": 0 } ] } ], "discount": 7.55, "quantity": 1, "item_price": 56, "unit_price": 56, "total_price": 56, "delta_quantity": 1, "item_promotion": { "type": "self_funded", "supplier_contribution": 0 }, "careem_discount_amount": 0, "merchant_discount_amount": 7.55 } ], "notes": "", "price": { "service_fee": 3.95, "delivery_fee": 7.5, "tax_percentage": 0, "careem_promo_amount": 0, "total_taxable_price": 241.63, "original_total_price": 263.58, "merchant_promo_amount": 0, "careem_discount_amount": 0, "merchant_discount_amount": 33.4, "free_delivery_discount_value": 7.5 }, "branch": { "id": "test_id", "name": "test", "state": "MAPPED", "active": true, "brand_id": "test_brand_id", "catalog_id": null, "created_at": "2022-07-04T12:19:22Z", "updated_at": "2024-11-19T21:58:43Z" }, "status": "accepted", "captain": { "name": "", "phone_number": "" }, "cash_in": 0, "customer": { "name": "", "address": { "area": "", "city": "", "name": "", "note": "", "number": "", "street": "", "building": "", "location": { "lat": "", "lng": "" } }, "payment_type": "", "phone_number": 0 }, "metadata": { "order_instructions": { "merchant_notes": null, "merchant_instructions": null } }, "created_at": "2025-08-01T06:26:07Z", "updated_at": "2025-08-01T06:35:15Z", "is_scheduled": false, "delivery_type": "careem", "merchant_pay_type": "prepaid", "cancellation_reason": "" }, "event_type": "ORDER_ITEM_REPLACEMENT_ACCEPTED" } } } }, "responses": { "2XX": { "description": "Return any 2XX status to indicate that the data was received successfully" } }, "security": [] } } }, "components": { "schemas": { "CreateBrandRequest": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "string", "example": "KFC", "description": "A unique brand ID string provided by vendor or restaurant." }, "name": { "type": "string", "example": "KFC", "description": "The body required to create a brand" } } }, "Brand": { "type": "object", "required": [ "id", "name", "state", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "description": "A unique brand ID string provided by vendor or restaurant. brand.", "example": "123004" }, "name": { "type": "string", "description": "The name of the brand.", "example": "KFC" }, "state": { "type": "string", "description": "The state of this brand.", "example": "MAPPED", "enum": [ "UNMAPPED", "MAPPED" ], "default": [ "UNMAPPED" ] }, "created_at": { "type": "string", "description": "Time RFC3339 format in UTC in which the brand has been updated", "example": "2020-06-22T15:01:32.895Z" }, "updated_at": { "type": "string", "description": "Time RFC3339 format in UTC in which the brand has been updated", "example": "2020-06-22T15:01:32.895Z" } }, "description": "Contains brand information" }, "UpdateBrandRequest": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "example": "KFC" } }, "description": "The body required to update a brand" }, "DeleteBrandRequest": { "type": "object", "properties": { "message": { "type": "string", "example": "The brand was successfully deleted" } } }, "BrandList": { "type": "object", "properties": { "data": { "type": "array", "description": "brand", "items": { "$ref": "#/components/schemas/Brand" } }, "meta": { "type": "object", "description": "pagination meta data", "properties": { "total": { "type": "integer", "description": "total number of records in database", "example": 90 }, "page_size": { "type": "integer", "description": "total number of records in the current page", "example": 20 }, "page_number": { "type": "integer", "description": "The number of the current page", "example": 1 } } }, "links": { "type": "object", "description": "links previous and next pagination pages", "properties": { "prev": { "type": "string", "description": "url of the previous page", "example": "URL/api/brands?page_number=1" }, "next": { "type": "string", "description": "url of the next page", "example": "URL/api/brands?page_number=3" } } } }, "description": "list of brands" }, "Branch": { "type": "object", "required": [ "id", "name", "brand_id", "state", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "description": "The id of the branch", "example": "a34587b290784c06" }, "name": { "type": "string", "description": "The name of the branch.", "example": "KFC, JLT" }, "brand_id": { "type": "string", "description": "the parent brand id of this branch", "example": "1228a02e60e34037" }, "state": { "type": "string", "description": "The state of this branch.", "example": "MAPPED", "enum": [ "UNMAPPED", "MAPPED" ], "default": [ "UNMAPPED" ] }, "created_at": { "type": "string", "description": "Time RFC3339 format in UTC in which the brand has been updated", "example": "2020-06-22T15:01:32.895Z" }, "updated_at": { "type": "string", "description": "Time RFC3339 format in UTC in which the brand has been updated", "example": "2020-06-22T15:01:32.895Z" } }, "description": "Branch information" }, "DeleteBranchRequest": { "type": "object", "properties": { "message": { "type": "string", "example": "The branch was successfully deleted" } } }, "PutBranchRequest": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "example": "KFC, Marina" } }, "description": "The body required to create/update a branch" }, "UpdateBranchRequest": { "type": "object", "required": [ "name" ], "properties": { "active": { "type": "boolean", "example": true } }, "description": "The active field to make branch active or inactive." }, "BranchList": { "type": "object", "properties": { "data": { "type": "array", "description": "branch", "items": { "$ref": "#/components/schemas/Branch" } }, "meta": { "type": "object", "description": "pagination meta data", "properties": { "total": { "type": "integer", "description": "total number of records in database", "example": 90 }, "page_size": { "type": "integer", "description": "total number of records in the current page", "example": 20 }, "page_number": { "type": "integer", "description": "The number of the current page", "example": 1 } } }, "links": { "type": "object", "description": "links previous and next pagination pages", "properties": { "prev": { "type": "string", "description": "url of the previous page", "example": "URL/api/branches?page_number=1&page_size=20" }, "next": { "type": "string", "description": "url of the next page", "example": "URL/api/branches?page_number=3&page_size=20" } } } }, "description": "list of branches" }, "CreateFullCatalogItem": { "type": "object", "required": [ "id", "name", "active", "price" ], "properties": { "id": { "type": "string", "description": "A unique item ID string provided by vendor or restaurant.", "example": "pancakes" }, "deleted": { "type": "boolean", "description": "This field is used to delete item when only catalog difference is sent for updating.", "example": false }, "name": { "type": "string", "example": "Pancakes" }, "name_localized": { "type": "object", "items": { "$ref": "#/components/schemas/Localized" }, "example": { "en": "Pancakes", "ar": "" } }, "description": { "type": "string", "example": "Fresh egg and chocolate pancakes" }, "description_localized": { "type": "object", "items": { "$ref": "#/components/schemas/Localized" }, "example": { "en": "Fresh egg and chocolate pancakes", "ar": "" } }, "active": { "type": "boolean", "example": true }, "price": { "type": "integer", "example": 20 }, "calorie_counts": { "type": "string", "example": "200" }, "allergic_information": { "type": "string", "example": "allergic to eggs" }, "operational_hours": { "type": "array", "items": { "$ref": "#/components/schemas/OperationalHour" }, "example": [ { "shifts": [ { "start_time": "10:00", "end_time": "12:00" } ], "active": true, "day_of_week": 5 } ] }, "media": { "type": "string", "example": "https://picsum.photos/300.jpg" }, "priority": { "type": "integer", "description": "This field is used to specify the order in which this item should appear. The items with lower value are shown first. If this field is not sent then default priority will be 1 and ordering cannot be guaranteed.", "minimum": 1, "example": 3 }, "tags": { "type": "array", "items": { "type": "string", "enum": [ "careem-mealson" ] }, "description": "List of tags associated with the item. only predefined tags are allowed.", "example": [ "careem-mealson" ] }, "groups": { "type": "array", "items": { "type": "string" }, "example": [ "addons" ], "description": "All the IDs for the groups included in the request." } } }, "CreateFullCatalogCategory": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "string", "description": "A unique category ID string provided by vendor or restaurant.", "example": "breakfast" }, "deleted": { "type": "boolean", "description": "This field is used to delete category when only catalog difference is sent for updating.", "example": false }, "name": { "type": "string", "example": "Default" }, "name_localized": { "type": "object", "items": { "$ref": "#/components/schemas/Localized" }, "example": { "en": "Breakfast", "ar": "" } }, "description": { "type": "string", "example": "All the breakfast items" }, "description_localized": { "type": "object", "items": { "$ref": "#/components/schemas/Localized" }, "example": { "en": "All breakfast items", "ar": "" } }, "preparation_time": { "type": "integer", "example": 20 }, "priority": { "type": "integer", "example": 1, "description": "No two categories in a catalog can have same priority. This is a field which decides the order of categories shown in the mobile app. Categories with higher priority would be shown first. If this field is not sent then default priority will be 1 and ordering cannot be guaranteed." }, "media": { "type": "string", "example": "https://picsum.photos/300.jpg" }, "operational_hours": { "type": "array", "items": { "$ref": "#/components/schemas/OperationalHour" }, "example": [ { "shifts": [ { "start_time": "10:00", "end_time": "12:00" } ], "active": true, "day_of_week": 5 } ] }, "sub_categories": { "type": "array", "items": { "type": "string" }, "example": [ "breakfast" ], "description": "All the IDs for the sub_categories included in the request." }, "items": { "type": "array", "items": { "type": "string" }, "example": [ "pancakes" ], "description": "All the IDs for the items included in the request." } } }, "CreateFullCatalogSubCategory": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "string", "description": "A unique category ID string provided by vendor or restaurant.", "example": "breakfast" }, "deleted": { "type": "boolean", "description": "This field is used to delete category when only catalog difference is sent for updating.", "example": false }, "name": { "type": "string", "example": "Default" }, "name_localized": { "type": "object", "items": { "$ref": "#/components/schemas/Localized" }, "example": { "en": "Breakfast", "ar": "" } }, "description": { "type": "string", "example": "All the breakfast items" }, "description_localized": { "type": "object", "items": { "$ref": "#/components/schemas/Localized" }, "example": { "en": "All breakfast items", "ar": "" } }, "preparation_time": { "type": "integer", "example": 20 }, "media": { "type": "string", "example": "https://picsum.photos/300.jpg" }, "priority": { "type": "integer", "example": 1, "description": "No two categories in a catalog can have same priority. This is a field which decides the order of categories shown in the mobile app. Categories with higher priority would be shown first. If this field is not sent then default priority will be 1 and ordering cannot be guaranteed." }, "operational_hours": { "type": "array", "items": { "$ref": "#/components/schemas/OperationalHour" }, "example": [ { "shifts": [ { "start_time": "10:00", "end_time": "12:00" } ], "active": true, "day_of_week": 5 } ] }, "items": { "type": "array", "items": { "type": "string" }, "example": [ "pancakes" ], "description": "All the IDs for the items included in the request." } } }, "CreateFullCatalogGroup": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "string", "description": "A unique group ID string provided by vendor or restaurant.", "example": "syrups" }, "deleted": { "type": "boolean", "description": "This field is used to delete group when only catalog difference is sent for updating.", "example": false }, "name": { "type": "string", "example": "addons" }, "name_localized": { "type": "object", "items": { "$ref": "#/components/schemas/Localized" }, "example": { "en": "Pancake add-ons", "ar": "" } }, "description": { "type": "string", "example": "Add-ons for pancakes" }, "description_localized": { "type": "object", "items": { "$ref": "#/components/schemas/Localized" }, "example": { "en": "Add-ons for pancakes", "ar": "" } }, "multi_select": { "type": "boolean", "description": "This field is used to specify whether the options inside this group can be selected more than once.
\nThe validation rules are as follows:

\nWhen multi_select is false:
\n  The group min must be between 0 and number of group options. (0 <= Group Min <= number of group options)
\n  The group max must be between the group min and number of group options. (Group Min <= Group Max <= number of group options)

\nWhen multi_select is true:
\n  The group min must be greater than 1. (Group Min > 1)
\n  The group max must be equal to the group min. (Group Max = Group Min)

\nAdditionally, when the group object has nested groups, setting multi_select to true is not allowed.\n", "example": false }, "min": { "type": "integer", "example": 1, "description": "This field is used to specify the minimum number of options that can be selected from this group.
\nCorresponding Item will become unavailable if the number of available options in this group is less than the min value.
\n" }, "max": { "type": "integer", "example": 2 }, "priority": { "type": "integer", "description": "This field is used to specify the order in which this group should appear. The groups with lower value are shown first. If this field is not sent then default priority will be 1 and ordering cannot be guaranteed.", "minimum": 1, "example": 2 }, "options": { "type": "array", "items": { "type": "string" }, "example": [ "maple", "honey" ], "description": "All the IDs for the options included in the request." } } }, "CreateFullCatalogOption": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "string", "description": "A unique option ID string provided by vendor or restaurant.", "example": "syrup" }, "deleted": { "type": "boolean", "description": "This field is used to delete option when only catalog difference is sent for updating.", "example": false }, "name": { "type": "string", "example": "Syrup" }, "name_localized": { "type": "object", "items": { "$ref": "#/components/schemas/Localized" }, "example": { "en": "Syrup", "ar": "" } }, "active": { "type": "boolean", "example": true }, "price": { "type": "integer", "example": 20 }, "priority": { "type": "integer", "description": "This field is used to specify the order in which this option should appear. The options with lower value are shown first. If this field is not sent then default priority will be 1 and ordering cannot be guaranteed.", "minimum": 1, "example": 3 }, "groups": { "type": "array", "items": { "type": "string" }, "example": [ "choose-syrup" ], "description": "All the IDs for the nested groups included in the request." } } }, "CreateFullCatalogRequest": { "type": "object", "required": [ "catalog" ], "properties": { "diff": { "type": "boolean", "example": false, "description": "If false, the whole catalog will be created or overridden if already created against the catalog id provided. The entities provided with IDs will be overridden or created. The entities missing from previous request will be deleted. If true, then only categories, items, options and groups provided will be added/updated as per the respective IDs. Deletion is not supported when diff is sent as true.", "default": false }, "catalog": { "type": "object", "required": [ "id", "name", "currency_id" ], "properties": { "id": { "type": "string", "example": "DefaultCatalog", "description": "A unique string identifier for catalog provided by restaurant. Since, it is a unique string identifier, it can have values as \"Default catalog\" or \"123006\"." }, "name": { "type": "string", "example": "Default" }, "include_tax": { "type": "boolean", "example": true, "description": "true if the tax is already included in the items/options prices.", "default": false }, "tax": { "type": "number", "example": 5.2, "description": "The tax percentage float value" }, "avg_price": { "type": "number", "example": 12.25, "description": "The price is a float value." }, "file": { "type": "string", "example": "https://loremflickr.com/cache/resized/65535_49625844823_baed6d35f9_320_240_g.jpg", "description": "Media file for catalog" }, "currency_id": { "type": "integer", "description": "The currency used for catalog. It is the integer ID corresponding to a currency. Allowed values are 1-14 with respective currency names and codes as follows:
\n\n```text\n | ID | Name | Code |\n |----|---------------------|------|\n | 1 | Dirham | AED |\n | 2 | Saudi Arabian Riyal | SAR |\n | 3 | Egyptian Pound | EGP |\n | 4 | Qatari Ria | QAR |\n | 5 | Lebanese pound | LBP |\n | 6 | Kuwaiti Dinar | KWD |\n | 7 | Jordanian Dinar | JOD |\n | 8 | Bahraini Dinar | BHD |\n | 9 | Singapore Dollar | SGD |\n | 10 | Iranian Rial | IRR |\n | 11 | Omani Rial | OMR |\n | 12 | Pakistani Rupee | PKR |\n | 13 | Australian Dollar | AUD |\n | 14 | Iraqi Dinar (IQD) | IQD |\n```\n", "example": 1 }, "category_ids": { "type": "array", "items": { "type": "string" }, "example": [ "breakfast" ], "description": "All the IDs for the categories included in the request." } } }, "categories": { "type": "array", "items": { "$ref": "#/components/schemas/CreateFullCatalogCategory" }, "description": "List of Categories to be added in catalog" }, "sub_categories": { "type": "array", "items": { "$ref": "#/components/schemas/CreateFullCatalogSubCategory" }, "description": "List of Sub Categories to be added in catalog" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/CreateFullCatalogItem" }, "description": "List of Items to be added in the catalog" }, "groups": { "type": "array", "items": { "$ref": "#/components/schemas/CreateFullCatalogGroup" }, "description": "List of Groups to be added in the catalog", "example": [ { "id": "addons", "deleted": false, "name": "Choose add-ons", "name_localized": { "en": "Choose add-ons", "ar": "" }, "description": "Add-ons for pancakes", "description_localized": { "en": "Add-ons for pancakes", "ar": "" }, "multi_select": false, "min": 1, "max": 2, "priority": 100, "options": [ "syrup", "butter" ] }, { "id": "choose-syrup", "deleted": false, "name": "Choose syrups", "name_localized": { "en": "Choose syrups", "ar": "" }, "description": "Select what type of syrup you want", "description_localized": { "en": "Syrup for pancakes", "ar": "" }, "multi_select": false, "min": 0, "max": 0, "priority": 101, "options": [ "maple", "honey" ] } ] }, "options": { "type": "array", "items": { "$ref": "#/components/schemas/CreateFullCatalogOption" }, "description": "List of Options to be added in the catalog", "example": [ { "id": "syrup", "deleted": false, "name": "Syrup", "name_localized": { "en": "Syrup", "ar": "" }, "active": true, "price": 10, "priority": 100, "groups": [ "choose-syrup" ] }, { "id": "butter", "deleted": false, "name": "Butter", "name_localized": { "en": "Butter", "ar": "" }, "active": true, "price": 5, "priority": 101 }, { "id": "maple", "deleted": false, "name": "Maple syrup", "name_localized": { "en": "Maple syrup", "ar": "" }, "active": true, "price": 1, "priority": 500 }, { "id": "honey", "deleted": false, "name": "Honey syrup", "name_localized": { "en": "Honey syrup", "ar": "" }, "active": true, "price": 1, "priority": 501 } ] }, "item_categories": { "type": "array", "description": "Per-category overrides for items. Use to move an item between categories atomically in a single diff:true request. Each entry overrides the base item definition for a specific (item_id, category_id) pair.", "items": { "$ref": "#/components/schemas/ItemCategory" }, "example": [ { "item_id": "item-1", "category_id": "cat-A", "deleted": true } ] } } }, "UpdateFullCatalogItem": { "type": "object", "required": [ "id", "active" ], "properties": { "id": { "type": "string", "description": "A unique item ID string provided by vendor or restaurant.", "example": "pancakes" }, "deleted": { "type": "boolean", "description": "This field is used to delete item when only catalog difference is sent for updating.", "example": false }, "name": { "type": "string", "example": "Pancakes" }, "name_localized": { "type": "object", "items": { "$ref": "#/components/schemas/Localized" }, "example": { "en": "Pancakes", "ar": "" } }, "description": { "type": "string", "example": "Fresh egg and chocolate pancakes" }, "description_localized": { "type": "object", "items": { "$ref": "#/components/schemas/Localized" }, "example": { "en": "Fresh egg and chocolate pancakes", "ar": "" } }, "active": { "type": "boolean", "example": true }, "price": { "type": "integer", "example": 20 }, "calorie_counts": { "type": "string", "example": "200" }, "allergic_information": { "type": "string", "example": "allergic to eggs" }, "operational_hours": { "type": "array", "items": { "$ref": "#/components/schemas/OperationalHour" }, "example": [ { "shifts": [ { "start_time": "10:00", "end_time": "12:00" } ], "active": true, "day_of_week": 5 } ] }, "media": { "type": "string", "example": "https://picsum.photos/300.jpg" }, "priority": { "type": "integer", "description": "This field is used to specify the order in which this item should appear. The items with lower value are shown first. If this field is not sent then default priority will be 1 and ordering cannot be guaranteed.", "minimum": 1, "example": 3 }, "tags": { "type": "array", "items": { "type": "string", "enum": [ "careem-mealson" ] }, "description": "List of tags associated with the item, only predefined tags are allowed.", "example": [ "careem-mealson" ] }, "groups": { "type": "array", "items": { "type": "string" }, "example": [ "addons" ], "description": "All the IDs for the groups included in the request." } } }, "UpdateFullCatalogCategory": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string", "description": "A unique category ID string provided by vendor or restaurant.", "example": "breakfast" }, "deleted": { "type": "boolean", "description": "This field is used to delete category when only catalog difference is sent for updating.", "example": false }, "name": { "type": "string", "example": "Default" }, "name_localized": { "type": "object", "items": { "$ref": "#/components/schemas/Localized" }, "example": { "en": "Breakfast", "ar": "" } }, "description": { "type": "string", "example": "All the breakfast items" }, "description_localized": { "type": "object", "items": { "$ref": "#/components/schemas/Localized" }, "example": { "en": "All breakfast items", "ar": "" } }, "preparation_time": { "type": "integer", "example": 20 }, "priority": { "type": "integer", "example": 1, "description": "No two categories in a catalog can have same priority. This is a field which decides the order of categories shown in the mobile app. Categories with higher priority would be shown first. If this field is not sent then default priority will be 1 and ordering cannot be guaranteed." }, "operational_hours": { "type": "array", "items": { "$ref": "#/components/schemas/OperationalHour" }, "example": [ { "shifts": [ { "start_time": "10:00", "end_time": "12:00" } ], "active": true, "day_of_week": 5 } ] }, "sub_categories": { "type": "array", "items": { "type": "string" }, "example": [ "breakfast" ], "description": "All the IDs for the sub categories included in the request." }, "items": { "type": "array", "items": { "type": "string" }, "example": [ "pancakes" ], "description": "All the IDs for the items included in the request." } } }, "UpdateFullCatalogSubCategory": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string", "description": "A unique sub category ID string provided by vendor or restaurant.", "example": "breakfast" }, "deleted": { "type": "boolean", "description": "This field is used to delete sub category when only catalog difference is sent for updating.", "example": false }, "name": { "type": "string", "example": "Default" }, "name_localized": { "type": "object", "items": { "$ref": "#/components/schemas/Localized" }, "example": { "en": "Breakfast", "ar": "" } }, "description": { "type": "string", "example": "All the breakfast items" }, "description_localized": { "type": "object", "items": { "$ref": "#/components/schemas/Localized" }, "example": { "en": "All breakfast items", "ar": "" } }, "preparation_time": { "type": "integer", "example": 20 }, "priority": { "type": "integer", "example": 1, "description": "No two sub categories in a category can have same priority. This is a field which decides the order of sub categories shown in the mobile app. Sub Categories with higher priority would be shown first. If this field is not sent then default priority will be 1 and ordering cannot be guaranteed." }, "operational_hours": { "type": "array", "items": { "$ref": "#/components/schemas/OperationalHour" }, "example": [ { "shifts": [ { "start_time": "10:00", "end_time": "12:00" } ], "active": true, "day_of_week": 5 } ] }, "items": { "type": "array", "items": { "type": "string" }, "example": [ "pancakes" ], "description": "All the IDs for the items included in the request." } } }, "UpdateFullCatalogGroup": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string", "description": "A unique group ID string provided by vendor or restaurant.", "example": "syrups" }, "deleted": { "type": "boolean", "description": "This field is used to delete group when only catalog difference is sent for updating.", "example": false }, "name": { "type": "string", "example": "Choose syrups" }, "name_localized": { "type": "object", "items": { "$ref": "#/components/schemas/Localized" }, "example": { "en": "Choose syrups", "ar": "" } }, "description": { "type": "string", "example": "Dressings for the salad" }, "description_localized": { "type": "object", "items": { "$ref": "#/components/schemas/Localized" }, "example": { "en": "Syrup for pancakes", "ar": "" } }, "multi_select": { "type": "boolean", "description": "This field is used to specify whether the options inside this group can be selected more than once.
\nThe validation rules are as follows:

\nWhen multi_select is false:
\n  The group min must be between 0 and number of group options. (0 <= Group Min <= number of group options)
\n  The group max must be between the group min and number of group options. (Group Min <= Group Max <= number of group options)

\nWhen multi_select is true:
\n  The group min must be greater than 1. (Group Min > 1)
\n  The group max must be equal to the group min. (Group Max = Group Min)

\nAdditionally, when the group object has nested groups, setting multi_select to true is not allowed.\n", "example": false }, "min": { "type": "integer", "example": 2, "description": "This field is used to specify the minimum number of options that can be selected from this group.
\nCorresponding Item will become unavailable if the number of available options in this group is less than the min value.
\n" }, "max": { "type": "integer", "example": 4 }, "priority": { "type": "integer", "description": "This field is used to specify the order in which this group should appear. The groups with lower value are shown first. If this field is not sent then default priority will be 1 and ordering cannot be guaranteed.", "minimum": 1, "example": 3 }, "options": { "type": "array", "items": { "type": "string" }, "example": [ "maple" ], "description": "All the IDs for the options included in the request." } } }, "UpdateFullCatalogOption": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string", "description": "A unique option ID string provided by vendor or restaurant.", "example": "maple" }, "deleted": { "type": "boolean", "description": "This field is used to delete option when only catalog difference is sent for updating.", "example": false }, "name": { "type": "string", "example": "Goat Cheese" }, "name_localized": { "type": "object", "items": { "$ref": "#/components/schemas/Localized" }, "example": { "en": "Maple syrup", "ar": "" } }, "active": { "type": "boolean", "example": true }, "price": { "type": "integer", "example": 20 }, "priority": { "type": "integer", "description": "This field is used to specify the order in which this option should appear. The options with lower value are shown first. If this field is not sent then default priority will be 1 and ordering cannot be guaranteed.", "minimum": 1, "example": 3 }, "groups": { "type": "array", "items": { "type": "string" }, "example": [ "choose-syrup" ], "description": "All the IDs for the nested groups included in the request." } } }, "UpdateFullCatalogRequest": { "type": "object", "required": [ "catalog" ], "properties": { "diff": { "type": "boolean", "example": false, "description": "If false, the whole catalog will be created or overridden if already created against the catalog id provided. The entities provided with IDs will be overridden or created. The entities missing from previous request will be deleted. If true, then only categories, items, options and groups provided will be added/updated as per the respective IDs. Deletion is not supported when diff is sent as true.", "default": false }, "catalog": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string", "example": "DefaultCatalog", "description": "A unique string identifier for catalog provided by restaurant. Since, it is a unique string identifier, it can have values as \"Default catalog\" or \"123006\"." }, "name": { "type": "string", "example": "Default" }, "include_tax": { "type": "boolean", "example": true, "description": "true if the tax is already included in the items/options prices.", "default": false }, "tax": { "type": "number", "example": 5.2, "description": "The tax percentage float value" }, "avg_price": { "type": "number", "example": 12.25, "description": "The price is a float value." }, "file": { "type": "string", "example": "https://loremflickr.com/cache/resized/65535_49625844823_baed6d35f9_320_240_g.jpg", "description": "Media file for catalog" }, "category_ids": { "type": "array", "items": { "type": "string" }, "example": [ "breakfast" ], "description": "All the IDs for the categories included in the request." } } }, "categories": { "type": "array", "items": { "$ref": "#/components/schemas/UpdateFullCatalogCategory" }, "description": "List of Categories to be added in catalog" }, "sub_categories": { "type": "array", "items": { "$ref": "#/components/schemas/UpdateFullCatalogSubCategory" }, "description": "List of Sub Categories to be added in catalog" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/UpdateFullCatalogItem" }, "description": "List of Items to be added in the catalog" }, "groups": { "type": "array", "items": { "$ref": "#/components/schemas/UpdateFullCatalogGroup" }, "description": "List of Groups to be added in the catalog", "example": [ { "id": "addons", "deleted": false, "name": "Choose add-ons", "name_localized": { "en": "Choose add-ons", "ar": "" }, "description": "Add-ons for pancakes", "description_localized": { "en": "Add-ons for pancakes", "ar": "" }, "multi_select": false, "min": 1, "max": 2, "priority": 100, "options": [ "syrup", "butter" ] }, { "id": "choose-syrup", "deleted": false, "name": "Choose syrups", "name_localized": { "en": "Choose syrups", "ar": "" }, "description": "Select what type of syrup you want", "description_localized": { "en": "Syrup for pancakes", "ar": "" }, "multi_select": false, "min": 0, "max": 0, "priority": 101, "options": [ "maple", "honey" ] } ] }, "options": { "type": "array", "items": { "$ref": "#/components/schemas/UpdateFullCatalogOption" }, "description": "List of Options to be added in the catalog", "example": [ { "id": "syrup", "deleted": false, "name": "Syrup", "name_localized": { "en": "Syrup", "ar": "" }, "active": true, "price": 10, "priority": 100, "groups": [ "choose-syrup" ] }, { "id": "butter", "deleted": false, "name": "Butter", "name_localized": { "en": "Butter", "ar": "" }, "active": false, "price": 5, "priority": 101 }, { "id": "maple", "deleted": false, "name": "Maple syrup", "name_localized": { "en": "Maple syrup", "ar": "" }, "active": true, "price": 1, "priority": 500 }, { "id": "honey", "deleted": false, "name": "Honey syrup", "name_localized": { "en": "Honey syrup", "ar": "" }, "active": false, "price": 1, "priority": 501 } ] }, "item_categories": { "type": "array", "description": "Per-category overrides for items. Use to move an item between categories atomically in a single diff:true request. Each entry overrides the base item definition for a specific (item_id, category_id) pair.", "items": { "$ref": "#/components/schemas/ItemCategory" }, "example": [ { "item_id": "item-1", "category_id": "cat-A", "deleted": true } ] } } }, "ItemCategory": { "type": "object", "required": [ "item_id", "category_id" ], "properties": { "item_id": { "type": "string", "description": "The ID of the item (must match an entry in the items array).", "example": "item-1" }, "category_id": { "type": "string", "description": "The ID of the category this override applies to.", "example": "cat-A" }, "deleted": { "type": "boolean", "description": "When true, the item is tombstoned under this specific category while remaining active under other categories.", "example": true } } }, "UpdateItemsRequest": { "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ItemStatusUpdate" }, "description": "List of items to be updated in catalog" } } }, "CreateFullCatalogStatusResponse": { "type": "object", "properties": { "request_id": { "type": "string", "example": "1400" }, "created_at": { "type": "string", "description": "Time RFC3339 format in UTC in which the catalog has been updated", "example": "2020-06-22T15:01:32.895Z" }, "url": { "type": "string", "description": "The URL to check status of the request.", "example": "/catalogs/status/1400" }, "message": { "type": "string", "example": "Please use this request ID string to check status of catalog upload request." } } }, "GetCatalogStatusResponse": { "type": "object", "properties": { "catalog_id": { "type": "string", "description": "The unique string identifier for catalog which restaurant provided while creating/updating catalog." }, "status": { "type": "string", "description": "The status of catalog upload processing.", "example": "COMPLETED", "enum": [ "COMPLETED", "FAILED", "PENDING" ], "default": [ "PENDING" ] }, "reason": { "type": "string", "description": "This field will be empty if status is COMPLETED or PENDING. If status is FAILED, then this field will have the log/reason why catalog creation has failed." } } }, "BranchStatusResponse": { "type": "object", "properties": { "branch_id": { "type": "string", "description": "The unique branch ID string provided by the vendor or restaurant." }, "status": { "type": "string", "description": "The current visibility status of the branch on SuperApp.", "example": "inactive", "enum": [ "active", "inactive", "offline" ] }, "reason": { "type": "string", "nullable": true, "description": "Human-readable reason the branch is not active. Null when the branch is active." }, "can_reactivate": { "type": "boolean", "nullable": true, "description": "Null when not applicable (active); true when the partner can self-reactivate (inactive); false when only Careem operations can reactivate (offline)." } } }, "OperationalHour": { "type": "object", "properties": { "shifts": { "type": "array", "items": { "$ref": "#/components/schemas/Shift" } }, "active": { "type": "boolean", "example": true }, "day_of_week": { "type": "integer", "example": 1 } } }, "VendorOperationalHour": { "type": "object", "properties": { "operational_hours": { "type": "array", "items": { "$ref": "#/components/schemas/OperationalHour" } } } }, "Shift": { "type": "object", "properties": { "start_time": { "type": "string", "example": "10:00", "description": "Accepted values (\"00:00\" to \"23:59\")" }, "end_time": { "type": "string", "example": "23:59", "description": "Accepted values (\"00:00\" to \"23:59\")" } } }, "Localized": { "type": "object", "properties": { "en": { "type": "string", "example": "English Name/Description" }, "ar": { "type": "string", "example": "Arabic Name/Description" } } }, "Order": { "type": "object", "description": "Order details", "required": [ "id", "status", "price", "branch", "items", "created_at", "updated_at" ], "properties": { "id": { "type": "integer", "description": "The id of the order", "example": 1001 }, "status": { "type": "string", "description": "The current status of the order", "example": "pending", "enum": [ "pending", "accepted", "cancelled", "delivered" ], "default": [ "pending" ] }, "merchant_pay_type": { "type": "string", "description": "Payment type for captain", "example": "cash" }, "delivery_type": { "type": "string", "description": "Delivery type for the order which could be either Careem or Merchant aka Self delivery. Self Delivery allows certain restaurants to deliver orders using their own rider fleet. POS APIs support self-delivery configuration.", "example": "careem", "enum": [ "careem", "merchant" ] }, "branch": { "$ref": "#/components/schemas/Branch" }, "notes": { "type": "string", "description": "Customer notes", "example": "please add extra ketchup" }, "price": { "$ref": "#/components/schemas/OrderPrice" }, "customer": { "$ref": "#/components/schemas/Customer" }, "captain": { "$ref": "#/components/schemas/Captain" }, "cash_in": { "type": "number", "multipleOf": 0.01, "description": "amount to be collected from customer if payment_type for customer is cash", "example": 41 }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/OrderItem" } }, "cancellation_reason": { "type": "string", "description": "The cancellation reason. This field is populated when the order is cancelled" }, "created_at": { "type": "string", "description": "Time RFC3339 format in UTC in which the brand has been updated", "example": "2020-06-22T15:01:32.895Z" }, "is_scheduled": { "type": "boolean", "description": "true if the order is scheduled", "example": false }, "prepare_time": { "type": "string", "description": "Time RFC3339 format in UTC at which the restaurant would start to prepare the order", "example": "2020-06-22T15:01:32.895Z" }, "pickup_time": { "type": "string", "description": "Time RFC3339 format in UTC at which the order would be picked up from the restaurant", "example": "2020-06-22T15:01:32.895Z" }, "updated_at": { "type": "string", "description": "Time RFC3339 format in UTC in which the brand has been updated", "example": "2020-06-22T15:01:32.895Z" }, "metadata": { "type": "object", "description": "Additional metadata related to the order", "properties": { "order_instructions": { "type": "object", "description": "Contains consistent and clear communication of merchant instructions, ensuring instructions are easily accessible and actionable.", "properties": { "merchant_notes": { "type": "string", "description": "text field for merchant notes" }, "merchant_instructions": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "icon_url": { "type": "string" }, "name_localized": { "type": "object", "properties": { "en": { "type": "string" }, "ar": { "type": "string" } } } } } } }, "example": { "merchant_notes": "Please make the order less spicy", "merchant_instructions": [ { "label": "INCLUDE_CUTLERY", "icon_url": "test.url", "name_localized": { "en": "Include Cutlery", "ar": "أدوات المائدة متضمنة" } } ] } }, "tags": { "type": "array", "items": { "type": "string" }, "description": "List of tags associated with the order, only predefined tags are allowed.", "enum": [ "careem-mealson" ], "example": [ "careem-mealson" ] } } } } }, "CancelledOrder": { "type": "object", "description": "Order details", "required": [ "id", "status", "price", "branch", "items", "created_at", "updated_at", "cancellation_reason" ], "properties": { "id": { "type": "string", "description": "The id of the order", "example": 1001 }, "status": { "type": "string", "description": "The current status of the order", "example": "cancelled", "enum": [ "pending", "accepted", "cancelled", "delivered" ], "default": [ "pending" ] }, "branch": { "$ref": "#/components/schemas/Branch" }, "notes": { "type": "string", "description": "Customer notes", "example": "please add extra ketchup" }, "price": { "$ref": "#/components/schemas/OrderPrice" }, "customer": { "$ref": "#/components/schemas/Customer" }, "captain": { "$ref": "#/components/schemas/Captain" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/OrderItem" } }, "cancellation_reason": { "type": "string", "description": "The cancellation reason. This field is populated when the order is cancelled", "example": "Item not available" }, "created_at": { "type": "string", "description": "Time RFC3339 format in UTC in which the brand has been updated", "example": "2020-06-22T15:01:32.895Z" }, "updated_at": { "type": "string", "description": "Time RFC3339 format in UTC in which the brand has been updated", "example": "2020-06-22T15:01:32.895Z" } } }, "OrderPrice": { "type": "object", "description": "Order price details", "properties": { "original_total_price": { "type": "number", "multipleOf": 0.01, "description": "is the total price of items and options without applying taxes nor discounts", "example": 22.5 }, "careem_discount_amount": { "type": "number", "multipleOf": 0.01, "description": "is the Careem contribution amount of the total promotion discount", "example": 5.5 }, "merchant_discount_amount": { "type": "number", "multipleOf": 0.01, "description": "is the Merchant contribution amount of the total promotion discount", "example": 5.5 }, "merchant_promo_amount": { "type": "number", "multipleOf": 0.01, "description": "is the Careem contribution amount of the total promo code discount", "example": 9 }, "careem_promo_amount": { "type": "number", "multipleOf": 0.01, "description": "is the Merchant contribution amount of the total promo code discount", "example": 0 }, "tax_percentage": { "type": "number", "multipleOf": 0.01, "description": "is the tax percentage of the order", "example": 5 }, "total_taxable_price": { "type": "number", "multipleOf": 0.01, "description": "is the total taxable amount of the order after applying taxes and the discount and adding delivery fees", "example": 19.63 }, "delivery_fee": { "type": "number", "multipleOf": 0.01, "description": "is the delivery fee charged", "example": 10 }, "free_delivery_discount_value": { "type": "number", "multipleOf": 0.01, "description": "is the discount amount on delivery fee. This value does not affect the total price of the order. However, it is important for the partner to take this value into account when performing their calculations.", "example": 0 }, "service_fee": { "type": "number", "multipleOf": 0.01, "description": "is the service fee charged", "example": 5 }, "promo_code": { "type": "string", "description": "Promotion code applicable for the order", "example": "FREEPROMO30" } } }, "Customer": { "type": "object", "description": "information about the owner of the order in case of a self delivery orders", "required": [ "name", "phone_number" ], "properties": { "name": { "type": "string", "description": "the name of the customer", "example": "Derek Falcon" }, "phone_number": { "type": "string", "description": "the phone number of the customer", "example": 971588371761 }, "address": { "$ref": "#/components/schemas/Address" }, "payment_type": { "type": "string", "description": "the payment type chosen by the customer like cash, card etc", "example": "cash", "enum": [ "cash", "card", "wallet", "apple_pay" ] } } }, "Captain": { "type": "object", "description": "the captain who is going to deliver the order", "required": [ "name", "phone_number", "eta" ], "properties": { "name": { "type": "string", "description": "the name of the driver", "example": "Derek Falcon" }, "phone_number": { "type": "string", "description": "the phone number of the driver", "example": 971582666112 }, "eta": { "type": "string", "description": "is captain-to-merchant ETA in UTC using the RFC3339 format and is provided only in the pending event. This attribute will be absent if unavailable.", "example": "2024-09-01T15:01:32.895Z" } } }, "Address": { "type": "object", "description": "show address details", "required": [ "name", "location", "number", "building", "street", "area", "city", "note" ], "properties": { "name": { "type": "string", "description": "name of address", "example": "Work" }, "location": { "type": "object", "description": "geolocation of the address", "required": [ "lat", "lng" ], "properties": { "lat": { "type": "string", "description": "the latitude of the address location", "example": "-39.65539" }, "lng": { "type": "string", "description": "the longitude of the address location", "example": "-31.78606" } } }, "number": { "type": "string", "description": "the number of the flat/villa", "example": "G04" }, "building": { "type": "string", "description": "the name of the building", "example": "'204', '1A'" }, "street": { "type": "string", "description": "the name of the street", "example": "3075 Dye Street" }, "area": { "type": "string", "description": "the name of the area", "example": "Marina" }, "city": { "type": "string", "description": "the name of the city", "example": "Dubai" }, "note": { "type": "string", "description": "additional notes or landmarks" } } }, "ItemStatusUpdate": { "type": "object", "description": "represents single item update payload", "required": [ "id", "status" ], "properties": { "id": { "type": "string", "description": "the id of the item", "example": "30" }, "status": { "type": "string", "description": "the status/availability of the item. Supported values [\"active\", \"inactive\"]", "example": "active" } } }, "ItemNestedGroup": { "type": "object", "description": "represents single nested group for an option", "required": [ "id", "options" ], "properties": { "id": { "type": "string", "description": "the id of the group", "example": "31" }, "options": { "type": "array", "description": "the options of the items", "items": { "$ref": "#/components/schemas/ItemNestedOption" } } } }, "ItemNestedOption": { "type": "object", "description": "represents a single nested option inside a nested group", "required": [ "id", "quantity", "total_price" ], "properties": { "id": { "type": "string", "description": "the id of the option", "example": "130" }, "quantity": { "type": "integer", "description": "is the quantity of the options selected", "example": 1 }, "discount": { "type": "number", "multipleOf": 0.01, "description": "is the total discount on the option", "example": 0 }, "careem_discount_amount": { "type": "number", "multipleOf": 0.01, "description": "is the Careem contribution amount of the discount", "example": 0 }, "merchant_discount_amount": { "type": "number", "multipleOf": 0.01, "description": "is the Merchant contribution amount of the discount", "example": 0 }, "total_price": { "type": "number", "multipleOf": 0.01, "description": "the total price of the selected options without applying taxes", "example": 0 } } }, "ItemGroup": { "type": "object", "description": "represents single group for an item", "required": [ "id" ], "properties": { "id": { "type": "string", "description": "the id of the group", "example": "30" }, "options": { "type": "array", "description": "the options of the items", "items": { "$ref": "#/components/schemas/ItemOption" } } } }, "ItemOption": { "type": "object", "description": "represents a single option inside an item", "required": [ "id", "quantity", "total_price" ], "properties": { "id": { "type": "string", "description": "the id of the option", "example": "129" }, "quantity": { "type": "integer", "description": "is the quantity of the options selected", "example": 2 }, "discount": { "type": "number", "multipleOf": 0.01, "description": "is the total discount on the option", "example": 1.5 }, "careem_discount_amount": { "type": "number", "multipleOf": 0.01, "description": "is the Careem contribution amount of the discount", "example": 0.75 }, "merchant_discount_amount": { "type": "number", "multipleOf": 0.01, "description": "is the Merchant contribution amount of the discount", "example": 0.75 }, "total_price": { "type": "number", "multipleOf": 0.01, "description": "the total price of the selected options without applying taxes", "example": 2.25 }, "groups": { "type": "array", "description": "Nested Modifiers allow nesting of the same item and its children options being shown under it instead of scrolling through.", "items": { "$ref": "#/components/schemas/ItemNestedGroup" } } } }, "OrderItem": { "type": "object", "description": "represents a single item inside the order", "required": [ "id", "quantity", "options", "item_price", "total_price", "discount", "careem_discount_amount", "merchant_discount_amount", "tags" ], "properties": { "id": { "type": "string", "description": "is the id of the item", "example": "345" }, "quantity": { "type": "integer", "description": "the total number of items selected", "example": 2 }, "groups": { "type": "array", "description": "the groups of the items", "items": { "$ref": "#/components/schemas/ItemGroup" } }, "unit_price": { "type": "number", "multipleOf": 0.01, "description": "single item price", "example": 9 }, "item_price": { "type": "number", "multipleOf": 0.01, "description": "is the unit_price * quantity", "example": 18 }, "total_price": { "type": "number", "multipleOf": 0.01, "description": "total price of this item with the options", "example": 22.5 }, "discount": { "type": "number", "multipleOf": 0.01, "description": "is the total discount on this item", "example": 9.5 }, "careem_discount_amount": { "type": "number", "multipleOf": 0.01, "description": "is the Careem contribution amount of the discount", "example": 4.75 }, "merchant_discount_amount": { "type": "number", "multipleOf": 0.01, "description": "is the Merchant contribution amount of the discount", "example": 4.75 }, "notes": { "type": "string", "description": "instructions, comments, notes for an item", "example": "Allergic to peanuts" }, "tags": { "type": "array", "description": "List of tags associated with the item, only predefined tags are allowed", "items": { "type": "string" }, "enum": [ "careem-mealson" ], "example": [ "careem-mealson" ] } } }, "OrderList": { "type": "object", "properties": { "data": { "type": "array", "description": "order", "items": { "$ref": "#/components/schemas/Order" } }, "meta": { "type": "object", "description": "pagination meta data", "properties": { "total": { "type": "integer", "description": "total number of records in database", "example": 90 }, "page_size": { "type": "integer", "description": "total number of records in the current page", "example": 20 }, "page_number": { "type": "integer", "description": "The number of the current page", "example": 1 } } }, "links": { "type": "object", "description": "links previous and next pagination pages", "properties": { "prev": { "type": "string", "description": "url of the previous page", "example": "URL/api/orders?page_number=1" }, "next": { "type": "string", "description": "url of the next page", "example": "URL/api/orders?page_number=3" } } } }, "description": "list of orders" }, "UpdateOrderRequest": { "type": "object", "required": [ "state", "cancellation_reason" ], "properties": { "state": { "type": "string", "description": "The state of the order.\n\nWe've recently introduced the `ready` state, which enables partners' to achieve more accurate tracking of their orders.\n", "enum": [ "accepted", "ready", "cancelled" ], "example": "cancelled" }, "cancellation_reason": { "type": "string", "description": "Please select cancellation reason from the predefined list. These reasons are case-sensitive.", "enum": [ "ITEM_PERMANENTLY_NOT_AVAILABLE", "ITEM_TEMPORARILY_UNAVAILABLE", "KITCHEN_TOO_BUSY_TO_PREPARE_ORDER", "OUT_OF_KITCHEN_OPERATIONAL_HOURS", "OUTLET_CLOSED", "PARTNER_POS_OUTAGE", "PARTNER_ORDER_TIMEOUT", "OTHER" ], "example": "ITEM_TEMPORARILY_UNAVAILABLE" }, "unavailable_items": { "type": "array", "description": "Optional list of items that are unavailable and caused the order cancellation.\nApplicable when `cancellation_reason` is `ITEM_PERMANENTLY_NOT_AVAILABLE` or `ITEM_TEMPORARILY_UNAVAILABLE`.\n", "items": { "$ref": "#/components/schemas/CancellationItem" } } } }, "CancellationItem": { "type": "object", "required": [ "item_id", "item_type" ], "properties": { "item_id": { "type": "string", "description": "The unique identifier of the unavailable item.", "example": "item-123" }, "item_type": { "type": "string", "description": "The type of the unavailable item.", "enum": [ "item", "modifier_option" ], "example": "item" } } }, "TagOrderRequest": { "type": "object", "required": [ "tag" ], "properties": { "tag": { "type": "string", "description": "the tag to be added to the order", "example": "reject", "enum": [ "reject" ], "default": [ "reject" ] } } }, "StatusRequest": { "type": "object", "description": "represents a branch visibility status request", "required": [ "status_id" ], "properties": { "status_id": { "type": "integer", "description": "status of the branch which must take effect.", "example": 2 } } }, "StatusExpiriesRequest": { "type": "object", "description": "Represents a branch visibility status request", "required": [ "status_id", "till_time" ], "properties": { "status_id": { "type": "integer", "description": "Accepted values (2)", "example": 2 }, "till_time": { "type": "integer", "description": "Time in minutes until branch must stay in given status.", "example": 15 } } }, "OrderDelayRequest": { "type": "object", "required": [ "delay_in_minutes" ], "properties": { "delay_in_minutes": { "type": "integer", "maximum": 60, "description": "The time for order delay in minutes.\n", "example": 10 } } }, "OrderDelaySuccessResponse": { "type": "object", "properties": { "message": { "type": "string", "example": "Request for more time has been successfully processed" }, "status": { "type": "string", "example": "success" }, "pickup_time": { "type": "string", "example": "2025-05-15T13:45:00Z" }, "order_id": { "type": "string", "example": "157633" } } }, "OrderDelayFailureResponse": { "type": "object", "properties": { "message": { "type": "string", "example": "Order already assigned to captain" }, "status": { "type": "string", "example": "failure" }, "order_id": { "type": "string", "example": "157633" } } }, "BranchStatusExpiriesResponse": { "type": "object", "description": "response of successful branch status expiries transaction.", "required": [ "branch_id", "status_id", "start_date", "end_date", "created_at", "updated_at" ], "properties": { "branch_id": { "type": "string", "description": "vendor branch id", "example": "branch-id" }, "status_id": { "type": "integer", "description": "status id", "example": 2 }, "start_date": { "type": "string", "description": "effective start date and time of given status.", "example": "2021-10-25T15:03:17.131029Z" }, "end_date": { "type": "string", "description": "effective end date and time of given status.", "example": "2021-10-25T15:03:17.131029Z" }, "created_at": { "type": "string", "description": "effective created at date and time of given status.", "example": "2021-10-25T15:03:17.131029Z" }, "updated_at": { "type": "string", "description": "effective updated at date and time of given status.", "example": "2021-10-25T15:03:17.131029Z" } } }, "ForbiddenErrorResponse": { "type": "object", "properties": { "message": { "type": "string", "example": "Forbidden Error" }, "code": { "type": "string", "example": "FORBIDDEN_ERROR" }, "error_type": { "type": "string", "example": "ForbiddenError" }, "errors": { "type": "object", "properties": { "reason": { "type": "string", "example": "Catalog cannot be reset for a branch with catalog creation in progress. Please wait until the job has ended. OR Catalog cannot be reset for an active branch. Please deactivate the branch first: https://docs.careemnow.com/#operation/togglePOSIntegration" } } } } }, "ErrorResponse": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "description": "The generic structure of error responses" } }, "securitySchemes": { "CareemIDPClientCredentials": { "type": "oauth2", "description": "Please refer to [authentication section](#tag/Auth-overview) for details.", "flows": { "clientCredentials": { "tokenUrl": "https://identity.careem.com/token", "scopes": { "pos": "Allows you to manage stores, menus and orders" } } } } } }, "x-tagGroups": [ { "name": "Release Notes", "tags": [ "Release Notes" ] }, { "name": "Authentication", "tags": [ "Auth overview", "Auth endpoints", "Auth token", "Auth rate limiting" ] }, { "name": "Store API", "tags": [ "Store API overview", "Store API components", "Store API operational hours", "Store API endpoints", "Store API flows" ] }, { "name": "Catalog API", "tags": [ "Catalog API overview", "Catalog API components", "Catalog API endpoints", "Catalog API webhook events", "Catalog API flows", "Catalog API sample payloads" ] }, { "name": "Order API", "tags": [ "Order API overview", "Order API components", "Order API endpoints", "Order API webhook events", "Order API flows", "Order API pricing components", "Order API calculations" ] }, { "name": "FAQs & Troubleshooting", "tags": [ "FAQs & Troubleshooting" ] } ] }