{ "openapi": "3.0.3", "security": [], "info": { "title": "Keeta Basic API Reference", "version": "v.1.0.0", "contact": { "name": "Keeta Developer Website", "email": "https://developers.mykeeta.com/" }, "description": "This API provides basic functionality for Keeta platform integration, including webhook configuration, authorization management, and OAuth token operations.\n" }, "servers": [ { "url": "https://open.mykeeta.com/api/open/grocery" } ], "paths": { "/authorization/change/notification": { "post": { "operationId": "receiveAuthorizationChangeEvent", "summary": "Merchant Authorization Change Notification", "description": "**Event ID**: 9001\n\nThis webhook is sent by Keeta to **notify the third-party system when a merchant's authorization changes**.\n\n**Notes:**\n- The third-party system could choose to **expose this endpoint and process the notification**.\n", "x-codeSamples": [ { "lang": "cURL", "source": "curl -i -X POST \\\n 'https://{software_service_domain}/api/open/grocery/authorization/change/notification' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"opType\": 0,\n \"chainId\": \"4323\",\n \"chainName\": \"GUI JI\",\n \"authorizedVendors\": [\n {\n \"vendorId\": \"145541\",\n \"vendorName\": \"Downtown Vendor\",\n \"address\": \"123 Main Street\",\n \"longitude\": \"114.057868\",\n \"latitude\": \"22.543099\"\n }\n ]\n }'" } ], "servers": [ { "url": "https://{software_service_domain}/api/open/grocery", "variables": { "software_service_domain": { "default": "example.com", "description": "Domain of the partner software service." } } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthorizedResourceResponse" }, "example": { "opType": 0, "chainId": "4323", "chainName": "GUI JI", "authorizedVendors": [ { "vendorId": "145541", "vendorName": "Downtown Vendor", "address": "123 Main Street", "longitude": "114.057868", "latitude": "22.543099" } ] } } } }, "responses": { "204": { "description": "Request executed successfully. No content is returned." }, "400": { "$ref": "#/components/responses/CallbackBadRequest" }, "403": { "$ref": "#/components/responses/CallbackForbidden" }, "404": { "$ref": "#/components/responses/CallbackNotFound" }, "503": { "$ref": "#/components/responses/CallbackUnavailable" } } } }, "/orderNotification": { "post": { "operationId": "webhookOrder", "summary": "Order Notification", "description": "**Event ID**: 6001\n\nKeeta sends this webhook when a new order is created or when the order\nstatus or final item facts change.\n\nThe payload has the same shape as the Order Details response and always\nrepresents the latest complete order.\n\nPossible order status values are:\n\n- `RECEIVED`: The order has been accepted and is waiting for fulfillment processing.\n- `PICKED`: Picking is complete. Service providers must process this\n status and refresh the final picked item facts.\n- `READY_FOR_PICKUP`: Packing is complete and the order is available\n for rider pickup. Processing this status is optional for service\n providers.\n- `DISPATCHED`: The order has left the store.\n- `DELIVERED`: The order has been delivered and is complete.\n- `CANCELED`: The order was cancelled.\n\n**Notes:** In the event that Keeta's platform sends a new order\nnotification but does not receive an acknowledgment from the\ndeveloper's system, Keeta will attempt to resend the notification up\nto a maximum of three additional times.\n\n**⚠️ IMPORTANT: Amount Availability and Finality**\n\nThe current Grocery Order payload does not expose a dedicated merchant\nsettlement breakdown. Where merchant settlement amounts are made\navailable, they may be calculated asynchronously and may therefore be\nabsent, null, or incomplete when an order notification is first\nreceived. Service providers must not use merchant settlement amounts as\nhard dependencies in order-processing logic. If settlement data is\nmissing or incomplete, re-query the Order Details endpoint after a short\ndelay. Reconciliation, invoicing, and other downstream workflows must\ntolerate the temporary unavailability of settlement amounts without\nblocking overall order processing.\n\nThe fields under `payment` represent customer payment amounts, not\nmerchant settlement amounts, and are not subject to settlement\ncalculation delays. These values may still change while picking or item\nmodifications are in progress. After picking is complete, the customer\npayment amounts are final and will not change.\n", "requestBody": { "required": true, "description": "Latest complete order. This structure contains all the detailed information about the order (such as order delivery information, recipient information, cost information, etc.)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } }, "responses": { "2XX": { "description": "Webhook received successfully. No response body is required." }, "4XX": { "description": "The webhook was rejected and may be retried." }, "5XX": { "description": "The webhook could not be processed and may be retried." } } } }, "/promotion/offline/notification": { "post": { "operationId": "receivePromotionOfflineEvent", "summary": "Promotion Offline Notification", "description": "**Event ID**: 7001\n\nThis webhook is sent by Keeta to **notify the third-party system when an existing promotion is taken offline**.\n\n**Notes:**\n- Product price changes, product removals, or promotion conflicts and overrides may cause an existing promotion to be taken offline.\n- The **vendorId** field identifies the vendor associated with the offline promotion.\n- The **detail** field contains SKU-level promotion offline details.\n", "x-codeSamples": [ { "lang": "cURL", "source": "curl -i -X POST \\\n 'https://{domain_of_the_software_service}/api/open/grocery/promotion/offline/notification' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"vendorId\": \"id_12345\",\n \"detail\": [\n {\n \"skuId\": \"sku1\",\n \"discountValue\": 10,\n \"originalPrice\": 15,\n \"offlineTime\": \"2022-02-07T16:03:06Z\",\n \"offlineReason\": \"The item has been removed.\"\n }\n ]\n }'" } ], "servers": [ { "url": "https://{domain_of_the_software_service}/api/open/grocery", "variables": { "domain_of_the_software_service": { "default": "example.com", "description": "Domain of the partner software service." } } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PromotionOfflineEventRequest" }, "example": { "vendorId": "id_12345", "detail": [ { "skuId": "sku1", "discountValue": 10, "originalPrice": 15, "offlineTime": "2022-02-07T16:03:06Z", "offlineReason": "The item has been removed." } ] } } } }, "responses": { "204": { "description": "Request executed successfully. No content is returned." }, "400": { "$ref": "#/components/responses/CallbackBadRequest" }, "403": { "$ref": "#/components/responses/CallbackForbidden" }, "404": { "$ref": "#/components/responses/CallbackNotFound" }, "503": { "$ref": "#/components/responses/CallbackUnavailable" } } } }, "/asynchronization/task/notification": { "post": { "operationId": "asynchronizationTaskWebhook", "summary": "Asynchronization Task Notification", "description": "**Event ID**: 8001\n\nWhen Keeta's platform receives an asynchronous request, it creates an internal task for processing. Upon task completion (success or failure), Keeta will notify the vendor via this webhook.\n\n**Notes**\n- **`jobStatus` values:**\n - **`QUEUED`**: The job has not started.\n - **`INPROGRESS`**: The job is being processed.\n - **`COMPLETED`**: Processing has finished.\n - **`FAILED`**: the job is failed to excute.\n- When `jobStatus = COMPLETED`, the result will contain the task execution details, including vendors and SKUs that failed to create the promotion activity.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "taskType", "jobId", "jobStatus" ], "properties": { "taskType": { "type": "integer", "example": 1, "description": "Indicates the asynchronous task type corresponding to this notification.\n\n- **`1`**: Add Product Task\n- **`2`**: Update Product Task\n- **`3`**: Manage Promotion Task\n- **`4`**: Update Product and Promotion Task\n" }, "jobId": { "type": "string", "example": "id_12345", "description": "Job identifier from the response of the corresponding asynchronous task." }, "jobStatus": { "type": "string", "example": "COMPLETED", "description": "" }, "downloadUrl": { "type": "string", "format": "uri", "example": "https://example.com/feedback/a946a2c7/job.csv", "description": "Temporary URL to download a CSV report with item-level feedback, such as validation errors, detected duplicates, or formatting issues. **Only when the `jobStatus=COMPLETED` then the downloadUrl is available.**" }, "reason": { "type": "string", "example": "The job failed to execute.", "description": "The specific reasons when `jobStatus=FAILED`." } } } } } }, "responses": { "200": { "description": "Optimal http response status" }, "4xx": { "description": "Webhook call will be retried up to 3 times" }, "5xx": { "description": "Webhook call will be retried up to 3 times" } } } } }, "components": { "schemas": { "PromotionOfflineEventRequest": { "type": "object", "required": [ "vendorId", "detail" ], "properties": { "vendorId": { "type": "string", "example": "id_12345", "description": "Unique identifier of the vendor associated with the offline promotion." }, "detail": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/PromotionOfflineDetail" }, "description": "SKU-level details for promotions that were taken offline." } } }, "PromotionOfflineDetail": { "type": "object", "required": [ "skuId", "discountValue", "originalPrice", "offlineTime", "offlineReason" ], "properties": { "skuId": { "type": "string", "example": "sku1", "description": "Unique identifier of the SKU whose promotion was taken offline." }, "discountValue": { "type": "number", "format": "double", "example": 10, "description": "Discount value of the promotion before it was taken offline." }, "originalPrice": { "type": "number", "format": "double", "example": 15, "description": "Original price of the SKU." }, "offlineTime": { "type": "string", "format": "date-time", "example": "2022-02-07T16:03:06Z", "description": "Time when the promotion was taken offline, in UTC using ISO 8601 format." }, "offlineReason": { "type": "string", "example": "The item has been removed.", "description": "Reason why the promotion was taken offline." } } }, "PaginatedOrders": { "type": "object", "required": [ "orders", "pageNumber", "pageSize", "totalPages" ], "properties": { "orders": { "type": "array", "description": "Orders on the current page.", "items": { "$ref": "#/components/schemas/Order" }, "example": [] }, "pageNumber": { "type": "integer", "minimum": 1, "description": "Current page number.", "example": 1 }, "pageSize": { "type": "integer", "minimum": 1, "maximum": 500, "description": "Number of orders requested per page.", "example": 20 }, "totalPages": { "type": "integer", "minimum": 0, "description": "Total number of pages.", "example": 3 } } }, "Order": { "type": "object", "description": "Latest complete grocery order.", "required": [ "acceptedFor", "createdAt", "updatedAt", "comment", "orderCode", "orderId", "orderType", "client", "customer", "items", "payment", "status", "transportType" ], "properties": { "acceptedFor": { "type": "string", "format": "date-time", "nullable": true, "description": "Time stamp in UTC which indicates the estimated delivery time.", "example": "2022-02-07T16:03:06Z" }, "createdAt": { "type": "string", "format": "date-time", "description": "Time when the order was created, in UTC.", "example": "2024-09-30T10:00:36.947Z" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Time when the order was last updated, in UTC.", "example": "2024-09-30T10:05:36.947Z" }, "comment": { "type": "string", "description": "Comment or remark related to the order.", "example": "My first order" }, "orderCode": { "type": "string", "description": "Short code used when handing the order to a rider.", "example": "29332222" }, "orderId": { "type": "string", "description": "Unique Keeta order identifier.", "example": "756823555555859" }, "orderType": { "type": "string", "description": "How the customer receives the order.", "enum": [ "DELIVERY", "PICKUP" ], "example": "DELIVERY" }, "cancellation": { "allOf": [ { "$ref": "#/components/schemas/Cancellation" } ], "description": "Present only when the order status is `CANCELED`." }, "client": { "$ref": "#/components/schemas/Client" }, "customer": { "$ref": "#/components/schemas/Customer" }, "items": { "type": "array", "minItems": 1, "description": "Latest order item facts available from Keeta.", "items": { "$ref": "#/components/schemas/OrderItem" } }, "payment": { "$ref": "#/components/schemas/Payment" }, "status": { "type": "string", "description": "Current order lifecycle status.", "enum": [ "RECEIVED", "PICKED", "READY_FOR_PICKUP", "DISPATCHED", "DELIVERED", "CANCELED" ], "example": "RECEIVED" }, "transportType": { "type": "string", "description": "Party responsible for delivering the order.", "enum": [ "VENDOR_DELIVERY", "LOGISTICS_DELIVERY" ], "example": "LOGISTICS_DELIVERY" } }, "example": { "acceptedFor": "2022-02-07T16:03:06Z", "createdAt": "2024-09-30T10:00:36.947Z", "updatedAt": "2024-09-30T10:05:36.947Z", "comment": "My first order", "orderCode": "29332222", "orderId": "756823555555859", "orderType": "DELIVERY", "cancellation": { "cancelledBy": "CUSTOMER", "postPickedUp": false, "code": "500001", "reason": "ITEM_UNAVAILABLE" }, "client": { "chainId": "1297211", "countryCode": "SA", "name": "POS Test Vendor", "vendorId": "611469", "externalVendorId": "123456" }, "customer": { "id": "10000030108064", "deliveryAddress": { "apartment": "Big Ap******", "block": "Bcasca******", "building": "******", "city": "Berlin", "company": "Keeta", "country": "SA", "floor": "12", "formattedAddress": "", "instructions": "Leave at the reception", "latitude": 0, "longitude": 0, "number": "******", "street": "Evergreen Street", "zipcode": "28001" }, "name": "***", "phoneNumber": "***" }, "items": [ { "id": "1261779167", "barcode": [ "6281100875093" ], "name": "Test product", "originalPricing": { "pricingType": "UNIT", "quantity": 1, "totalPrice": 39.75, "unitPrice": 39.75, "listPrice": 39.75, "vatPercent": 0, "weight": 0 }, "pricing": { "pricingType": "UNIT", "quantity": 1, "totalPrice": 39.75, "unitPrice": 39.75, "vatPercent": 0, "weight": 0 }, "sku": 101049, "imageUrls": [ "https://images.mtkeeta.io/image.jpg" ], "status": "IN_CART", "promotion": [ { "name": "Drinks 0.5l and 1l on sale", "type": "STRIKETHROUGH", "discountAmount": 2.25, "sponsorships": [ { "sponsor": "VENDOR", "amount": 2.25 } ] } ] } ], "payment": { "additionalFees": { "tip": 1, "droneServiceFee": 0.5 }, "deliveryFee": 1, "differenceToMinimum": 0, "discount": -1, "discounts": [ { "name": "First discount", "value": -1 } ], "orderTotal": 41.75, "serviceFee": 0, "subTotal": 39.75, "totalTaxes": 0, "type": "PAID" }, "status": "RECEIVED", "transportType": "LOGISTICS_DELIVERY" } }, "Cancellation": { "type": "object", "required": [ "cancelledBy", "postPickedUp", "code" ], "properties": { "cancelledBy": { "type": "string", "description": "Party responsible for the cancellation.", "enum": [ "CUSTOMER", "VENDOR", "PLATFORM" ], "example": "CUSTOMER" }, "postPickedUp": { "type": "boolean", "description": "Whether the cancellation occurred after rider pickup.", "example": false }, "code": { "type": "string", "description": "Code indicating why the order was cancelled. This is the string\nrepresentation of `cancelCode` used by the Order Cancellation API.\n", "enum": [ "500000", "500001", "500002", "500003" ], "x-enumDescriptions": { "500000": "Other unspecified reasons; `reason` provides the specific cancellation explanation.", "500001": "Insufficient ingredients.", "500002": "Store temporarily closed.", "500003": "Staff shortage." }, "example": "500001" }, "reason": { "type": "string", "description": "Optional detailed cancellation reason mapped from the Keeta cancellation record. When `code` is `500000`, this field provides the specific cancellation explanation.", "example": "ITEM_UNAVAILABLE" } } }, "Client": { "type": "object", "description": "Chain and vendor information associated with the order.", "required": [ "chainId", "countryCode", "name", "vendorId" ], "properties": { "chainId": { "type": "string", "description": "Unique chain or brand identifier.", "example": "1297211" }, "countryCode": { "type": "string", "pattern": "^[A-Z]{2}$", "description": "Uppercase ISO 3166-1 alpha-2 market code, such as `SA`, `KW`, `QA`, `BH`, or `AE`.", "example": "SA" }, "name": { "type": "string", "description": "Vendor display name.", "example": "POS Test Vendor" }, "vendorId": { "type": "string", "description": "Unique Keeta platform vendor identifier.", "example": "611469" }, "externalVendorId": { "type": "string", "description": "Merchant's internal vendor identifier. Present only when the merchant has maintained a vendor mapping in Keeta.", "example": "123456" } } }, "Customer": { "type": "object", "description": "Customer and delivery destination information.", "required": [ "id", "deliveryAddress", "name", "phoneNumber" ], "properties": { "id": { "type": "string", "description": "Internal Keeta customer identifier.", "example": "10000030108064" }, "deliveryAddress": { "$ref": "#/components/schemas/DeliveryAddress" }, "name": { "type": "string", "description": "Masked customer name.", "example": "***" }, "phoneNumber": { "type": "string", "description": "Masked customer phone number, including country code when available.", "example": "***" } } }, "DeliveryAddress": { "type": "object", "description": "Structured customer delivery address.", "required": [ "formattedAddress", "latitude", "longitude" ], "properties": { "apartment": { "type": "string", "description": "Masked apartment or unit number.", "example": "Big Ap******" }, "block": { "type": "string", "description": "Masked block, district, phase, or estate information.", "example": "Bcasca******" }, "building": { "type": "string", "description": "Masked building name.", "example": "******" }, "city": { "type": "string", "description": "City name.", "example": "Berlin" }, "company": { "type": "string", "description": "Company or organization at the address.", "example": "Keeta" }, "country": { "type": "string", "description": "Market or country code.", "example": "SA" }, "floor": { "type": "string", "description": "Floor or unit information.", "example": "12" }, "formattedAddress": { "type": "string", "description": "Human-readable full address.", "example": "" }, "instructions": { "type": "string", "description": "Delivery instructions supplied with the address.", "example": "Leave at the reception" }, "latitude": { "type": "number", "format": "double", "minimum": -90, "maximum": 90, "description": "Delivery latitude.", "example": 0 }, "longitude": { "type": "number", "format": "double", "minimum": -180, "maximum": 180, "description": "Delivery longitude.", "example": 0 }, "number": { "type": "string", "description": "Masked street number.", "example": "******" }, "street": { "type": "string", "description": "Street name.", "example": "Evergreen Street" }, "zipcode": { "type": "string", "description": "Postal code.", "example": "28001" } } }, "OrderItem": { "type": "object", "description": "Order item, pricing, replacement, image, status, and promotion\ninformation.\n\nReplacement relationships use a child-to-parent reference. The\nreplacement item carries `replacedId`, which points to the `id` of the\noriginal item it replaces. The original item remains in `items` with\nstatus `REPLACED`, while each accepted replacement is represented as a\nseparate item with status `IN_CART`.\n\nOne original item can therefore be replaced by multiple items without\nusing an array: each replacement item uses the same original item ID as\nits `replacedId`. For example, if items B and C replace item A, both\n`B.replacedId` and `C.replacedId` are `A.id`.\n", "required": [ "id", "barcode", "name", "originalPricing", "pricing", "sku", "imageUrls", "status" ], "properties": { "id": { "type": "string", "description": "Unique order-item identifier.", "example": "1261779167" }, "barcode": { "type": "array", "description": "Product barcodes associated with the order item.", "items": { "type": "string" }, "example": [ "6281100875093" ] }, "name": { "type": "string", "description": "Product name.", "example": "Test product" }, "originalPricing": { "allOf": [ { "description": "Price and quantity originally ordered by the customer." }, { "$ref": "#/components/schemas/OriginalItemPricing" } ] }, "pricing": { "allOf": [ { "description": "Latest price and quantity available from Keeta." }, { "$ref": "#/components/schemas/CurrentItemPricing" } ] }, "replacedId": { "type": "string", "nullable": true, "description": "ID of the original order item replaced by this item. This field is\npresent only on a replacement item and points to another item in\nthe same order whose status is `REPLACED`. The replacement item\nmust have status `IN_CART` and a non-empty `name`.\n\nMultiple replacement items may use the same `replacedId` to\nrepresent one original item being replaced by multiple items. The\nvalue must not reference the current item itself. Omit this field\nfor original, unchanged, not-found, and independently added items.\n", "example": "1261779167" }, "sku": { "type": "string", "description": "Partner catalog SKU or open item code.", "example": "HSMVTE" }, "imageUrls": { "type": "array", "description": "Product image URLs sourced from `products[].picList`.", "items": { "type": "string", "format": "uri" }, "example": [ "https://images.talabat.io/image.jpg" ] }, "status": { "type": "string", "description": "Item status. Possible values are:\n\n- `NOT_PROCESSED`: The item's default status when the order is received.\n- `IN_CART`: The item is available in full or partial quantities for\n fulfillment. A replacement item also uses this status and points\n to the original item through `replacedId`.\n- `NOT_FOUND`: The item is out of stock and will not be fulfilled.\n- `REPLACED`: The original item is out of stock and was replaced by\n one or more items. Its `id` is referenced by each replacement\n item's `replacedId`.\n- `ADDITION`: The item was independently added by the picker and is\n not a replacement; `replacedId` is omitted.\n", "enum": [ "NOT_PROCESSED", "IN_CART", "NOT_FOUND", "REPLACED", "ADDITION" ], "example": "IN_CART" }, "promotion": { "type": "array", "nullable": true, "description": "Promotions applied to the item.", "items": { "$ref": "#/components/schemas/ItemPromotion" } } } }, "OriginalItemPricing": { "type": "object", "required": [ "pricingType", "quantity", "totalPrice", "unitPrice", "listPrice", "vatPercent", "weight" ], "properties": { "pricingType": { "type": "string", "description": "Pricing type indicates whether the item is priced by `UNIT` or by `KG`.", "enum": [ "UNIT", "KG" ], "example": "UNIT" }, "quantity": { "type": "number", "format": "double", "minimum": 0, "nullable": true, "description": "Quantity of order items as ordered by the customer. Applies when `pricingType` is `UNIT`.", "example": 1 }, "totalPrice": { "type": "number", "format": "double", "description": "Original total item amount in local currency.", "example": 39.75 }, "unitPrice": { "type": "number", "format": "double", "description": "Original unit price in local currency.", "example": 39.75 }, "listPrice": { "type": "number", "format": "double", "description": "Item price before discounts.", "example": 39.75 }, "vatPercent": { "type": "number", "format": "double", "minimum": 0, "default": 0, "description": "VAT percentage. Keeta has no source field, so the value is always `0`.", "example": 0 }, "weight": { "type": "number", "format": "double", "minimum": 0, "nullable": true, "description": "Weight of order items as ordered by the customer. Applies when `pricingType` is `KG`.", "example": 0 } } }, "CurrentItemPricing": { "type": "object", "required": [ "pricingType", "quantity", "totalPrice", "unitPrice", "vatPercent", "weight" ], "properties": { "pricingType": { "type": "string", "description": "Pricing type indicates whether the item is priced by `UNIT` or by `KG`.", "enum": [ "UNIT", "KG" ], "example": "UNIT" }, "quantity": { "type": "number", "format": "double", "minimum": 0, "nullable": true, "description": "Quantity of order items as fulfilled by the partner. Applies when `pricingType` is `UNIT`.", "example": 1 }, "totalPrice": { "type": "number", "format": "double", "description": "Latest total item amount in local currency.", "example": 39.75 }, "unitPrice": { "type": "number", "format": "double", "description": "Latest unit price in local currency.", "example": 39.75 }, "vatPercent": { "type": "number", "format": "double", "minimum": 0, "default": 0, "description": "VAT percentage. Keeta has no source field, so the value is always `0`.", "example": 0 }, "weight": { "type": "number", "format": "double", "minimum": 0, "nullable": true, "description": "Weight of order items as fulfilled by the partner. Applies when `pricingType` is `KG`.", "example": 0 } } }, "ItemPromotion": { "type": "object", "required": [ "name", "type", "discountAmount", "sponsorships" ], "properties": { "name": { "type": "string", "description": "Promotion display name.", "example": "Drinks 0.5l and 1l on sale" }, "type": { "type": "string", "description": "Promotion type.", "enum": [ "STRIKETHROUGH", "SAME_ITEM_BUNDLE" ], "example": "STRIKETHROUGH" }, "discountAmount": { "type": "number", "format": "double", "minimum": 0, "description": "Total promotion discount in local currency.", "example": 2.25 }, "sponsorships": { "type": "array", "description": "Contribution by each promotion sponsor.", "items": { "$ref": "#/components/schemas/PromotionSponsorship" } } } }, "PromotionSponsorship": { "type": "object", "required": [ "sponsor", "amount" ], "properties": { "sponsor": { "type": "string", "description": "Type of the sponsor. Currently, only `VENDOR` is supported.", "enum": [ "VENDOR" ], "example": "VENDOR" }, "amount": { "type": "number", "format": "double", "minimum": 0, "description": "Sponsor contribution in local currency.", "example": 2.25 } } }, "Payment": { "type": "object", "description": "Customer charges, discounts, totals, and payment type.", "required": [ "deliveryFee", "differenceToMinimum", "discount", "discounts", "orderTotal", "serviceFee", "subTotal", "totalTaxes", "type" ], "properties": { "additionalFees": { "type": "object", "nullable": true, "description": "Any fee not explicitly included in the other payment fields.", "properties": { "tip": { "type": "number", "format": "double", "minimum": 0, "description": "Tip charged in local currency." }, "droneServiceFee": { "type": "number", "format": "double", "minimum": 0, "description": "Drone service fee in local currency." } } }, "deliveryFee": { "type": "number", "format": "double", "description": "Delivery fee in local currency.", "example": 1 }, "differenceToMinimum": { "type": "number", "format": "double", "description": "Charge added to reach the minimum order value.", "example": 0 }, "discount": { "type": "number", "format": "double", "maximum": 0, "description": "Total discount as a negative amount, following Talabat semantics.", "example": -1 }, "discounts": { "type": "array", "description": "Detailed order-level discounts.", "items": { "$ref": "#/components/schemas/Discount" } }, "orderTotal": { "type": "number", "format": "double", "description": "Final amount payable by the customer.", "example": 41.75 }, "serviceFee": { "type": "number", "format": "double", "description": "Platform service fee.", "example": 0 }, "subTotal": { "type": "number", "format": "double", "description": "Item subtotal before delivery and service fees.", "example": 39.75 }, "totalTaxes": { "type": "number", "format": "double", "enum": [ 0 ], "description": "Tax amounts are not currently provided by this API contract, so\nthis value is fixed at 0.\n", "example": 0 }, "type": { "type": "string", "description": "Customer payment type.", "enum": [ "PAID", "CASH_ON_DELIVERY" ], "example": "PAID" } } }, "Discount": { "type": "object", "required": [ "name", "value" ], "properties": { "name": { "type": "string", "description": "Discount name.", "example": "First discount" }, "value": { "type": "number", "format": "double", "maximum": 0, "description": "Discount as a negative amount, following Talabat semantics.", "example": -1 } } }, "TokenResponse": { "type": "object", "properties": { "accessToken": { "type": "string", "example": "eyJhbGciOiJQUzI1NiIsInR5cCI6IkpXVCJ9eyJ1dWlkIjoiVEVTVCJ9", "description": "A short-lived JSON Web Token used to authenticate Partner API requests." }, "tokenType": { "type": "string", "example": "Bearer", "description": "The token type used in the Authorization header." }, "expiresIn": { "type": "integer", "example": 7200, "description": "The access token lifetime in seconds. Cache and reuse the token until it expires, using this value as the cache time-to-live." } } }, "OAuthErrorResponse": { "type": "object", "properties": { "code": { "type": "string", "example": "INVALID_REQUEST", "description": "OAuth error code." }, "message": { "type": "string", "example": "Invalid client credentials", "description": "Human-readable explanation of the OAuth error." } } }, "AuthorizedResourceResponse": { "type": "object", "description": "Merchant authorization information.", "properties": { "opType": { "type": "integer", "format": "int32", "enum": [ 0, 1 ], "example": 0, "description": "Operation type. 0 indicates new store authorization; 1 indicates store authorization removal." }, "chainId": { "type": "string", "example": "4323", "description": "Chain ID of the authorized vendors." }, "chainName": { "type": "string", "example": "GUI JI", "description": "Chain name of the authorized vendors." }, "authorizedVendors": { "type": "array", "description": "List of authorized vendors.", "items": { "$ref": "#/components/schemas/AuthorizedShop" } } } }, "AuthorizedShop": { "type": "object", "properties": { "vendorId": { "type": "string", "example": "145541", "description": "Vendor ID." }, "vendorName": { "type": "string", "example": "Downtown Vendor", "description": "Vendor name." }, "address": { "type": "string", "example": "123 Main Street", "description": "Vendor address." }, "longitude": { "type": "string", "example": "114.057868", "description": "Vendor longitude." }, "latitude": { "type": "string", "example": "22.543099", "description": "Vendor latitude." } } }, "CallbackErrorResponse": { "type": "object", "properties": { "title": { "type": "string", "example": "Unexpected error", "description": "Human-readable error title." }, "status": { "type": "integer", "format": "int32", "example": 500, "description": "Numeric error status supplied by the callback service." } } } }, "responses": { "CallbackBadRequest": { "description": "The callback request was invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CallbackErrorResponse" }, "example": { "title": "Unexpected error", "status": 500 } } } }, "CallbackForbidden": { "description": "The authenticated request violated an authorization rule.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CallbackErrorResponse" }, "example": { "title": "Unexpected error", "status": 500 } } } }, "CallbackNotFound": { "description": "The requested callback resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CallbackErrorResponse" }, "example": { "title": "Unexpected error", "status": 500 } } } }, "CallbackUnavailable": { "description": "The callback service is unavailable, under maintenance, or outside its operating window.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CallbackErrorResponse" }, "example": { "title": "Unexpected error", "status": 500 } } } } }, "securitySchemes": { "OAuth2ClientCredentials": { "type": "oauth2", "description": "OAuth 2.0 client credentials used by partner applications.", "flows": { "clientCredentials": { "tokenUrl": "https://api-docs.mykeeta.com/apis/yhsu3hu21ch23yabx4xuuuq7/basic/endpoints/generateaccesstoken", "scopes": {} } } }, "Signature": { "type": "apiKey", "description": "To enhance overall security, Keeta requires a signature in the Header when making requests to Keeta. Please refer to [Authorization Guide](https://api-docs.mykeeta.com/apis/yhsu3hu21ch23yabx4xuuuq7/docs/auth) for details.", "in": "header", "name": "Signature" } } } }