{"openapi":"3.1.0","info":{"title":"OrderGer Public API","version":"1.0.0","description":"Receive restaurant website orders instantly with a mobile alarm. Pay only for delivered orders ($0.05). First 100 completed orders free.","contact":{"email":"hamidalqwaysim@gmail.com"},"license":{"name":"Commercial"},"x-orderger-mcp":{"npm":"orderger-mcp","description":"Native MCP support for Claude / Cursor / Windsurf / Continue. Run via npx -y orderger-mcp."}},"servers":[{"url":"https://orderger-api.hamidalqwaysim.workers.dev"}],"security":[{"apiKey":[]},{"branch":[]}],"paths":{"/api/v1/orders":{"post":{"operationId":"createOrder","summary":"Create a new order","description":"Forwards a customer order from the website to the OrderGer mobile app. Sandbox/test orders (via `test: true` or sandbox-flagged API key) are not billed.","security":[{"apiKey":[],"branch":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateOrderRequest"}}}},"responses":{"200":{"description":"Order received","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateOrderSuccess"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"Insufficient wallet balance; top up to receive live orders","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InsufficientBalance"}}}},"404":{"description":"Branch not found"},"409":{"description":"Duplicate order (same external_order_id already received)"},"429":{"description":"Rate limited (default 60/min per API key)"}}}},"/api/v1/orders/{id}":{"get":{"operationId":"getOrder","summary":"Get one order by OrderGer ID","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"OK"},"404":{"description":"Not found"}}},"patch":{"operationId":"updateOrder","summary":"Update editable order fields (customer, delivery, notes, payment_status, estimated_prep_minutes)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"apiKey":[]}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateOrderRequest"}}}},"responses":{"200":{"description":"OK"},"409":{"description":"Version conflict or order in final status"}}}},"/api/v1/orders/{id}/status":{"patch":{"operationId":"updateOrderStatus","summary":"Update order status","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"apiKey":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["status"],"properties":{"status":{"$ref":"#/components/schemas/OrderStatus"},"note":{"type":"string"}}}}}},"responses":{"200":{"description":"OK"}}}},"/api/v1/orders/{id}/cancel":{"post":{"operationId":"cancelOrder","summary":"Cancel an order","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"apiKey":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string"}}}}}},"responses":{"200":{"description":"OK"}}}},"/api/v1/branches":{"get":{"operationId":"listBranches","summary":"List branches accessible to this API key","security":[{"apiKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"branches":{"type":"array","items":{"$ref":"#/components/schemas/Branch"}}}}}}}}}},"/api/v1/test-order":{"post":{"operationId":"getSampleTestPayload","summary":"Returns a sample order payload — useful for first-time integration testing","security":[{"apiKey":[]}],"responses":{"200":{"description":"OK"}}}},"/install/{token}":{"get":{"operationId":"fetchInstallBundle","summary":"Fetch an install bundle — returns API key, branch ID, base URL, snippets. Designed for non-MCP AI agents to fetch via simple HTTP.","parameters":[{"name":"token","in":"path","required":true,"schema":{"type":"string"},"description":"Single-use install token. Created in the owner dashboard."},{"name":"stack","in":"query","required":false,"schema":{"type":"string","enum":["wordpress_woocommerce","php_curl","laravel","node_express","nextjs_app_router","nextjs_pages_router","nestjs","django","flask","fastapi","rails","go","dotnet","java_spring","shopify","curl_bash"]},"description":"Pick the stack for which to generate a tailored snippet."}],"responses":{"200":{"description":"OK — JSON bundle with everything the AI needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InstallBundle"}}}},"404":{"description":"Token invalid or expired"}}}}},"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"Use the OrderGer API key as a bearer token (og_live_xxx or og_test_xxx)."},"branch":{"type":"apiKey","in":"header","name":"X-OrderGer-Branch-ID","description":"The branch to receive this order. Required if the API key is not scoped to a branch."}},"schemas":{"CreateOrderRequest":{"type":"object","required":["customer"],"properties":{"external_order_id":{"type":"string","description":"Your website's order ID. Used for de-duplication."},"branch_id":{"type":"string","description":"Branch ID. Overrides the X-OrderGer-Branch-ID header."},"test":{"type":"boolean","description":"Set true for a sandbox/test order. Sandbox orders are never billed."},"type":{"type":"string","enum":["delivery","pickup","dine_in"],"default":"delivery"},"estimated_prep_minutes":{"type":"integer","minimum":0},"integration_type":{"type":"string","enum":["woocommerce","php","nodejs","laravel","nextjs","ai_agent","custom","manual_test"]},"source":{"type":"object","properties":{"website_name":{"type":"string"},"domain":{"type":"string"},"page_url":{"type":"string","format":"uri"}}},"utm":{"type":"object","properties":{"source":{"type":"string"},"medium":{"type":"string"},"campaign":{"type":"string"}}},"customer":{"type":"object","required":["phone"],"properties":{"name":{"type":"string"},"phone":{"type":"string"},"whatsapp":{"type":"string"},"email":{"type":"string","format":"email"}}},"delivery":{"type":"object","properties":{"city":{"type":"string"},"area":{"type":"string"},"address":{"type":"string"},"building":{"type":"string"},"floor":{"type":"string"},"apartment":{"type":"string"},"landmark":{"type":"string"},"lat":{"type":"number"},"lng":{"type":"number"},"maps_url":{"type":"string","format":"uri"},"notes":{"type":"string"}}},"items":{"type":"array","items":{"type":"object","required":["name","quantity","total"],"properties":{"name":{"type":"string"},"quantity":{"type":"integer"},"unit_price":{"type":"number"},"total":{"type":"number"},"notes":{"type":"string"},"image_url":{"type":"string","format":"uri"},"options":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"value":{"type":"string"},"extra_price":{"type":"number"}}}}}}},"pricing":{"type":"object","properties":{"subtotal":{"type":"number"},"delivery_fee":{"type":"number"},"discount":{"type":"number"},"tax":{"type":"number"},"total":{"type":"number"},"currency":{"type":"string","default":"JOD"}}},"payment":{"type":"object","properties":{"method":{"type":"string","enum":["cash_on_delivery","card","paypal","stripe","wallet","other"]},"status":{"type":"string","enum":["unpaid","paid","refunded"]}}},"delivery_finance":{"type":"object","properties":{"fee_charged_to_customer":{"type":"number"},"actual_cost_to_restaurant":{"type":"number"},"currency":{"type":"string"},"provider":{"type":"string"},"courier_name":{"type":"string"},"courier_phone":{"type":"string"}}},"notes":{"type":"string"}}},"UpdateOrderRequest":{"type":"object","properties":{"expected_version":{"type":"integer"},"customer_name":{"type":"string"},"customer_phone":{"type":"string"},"customer_whatsapp":{"type":"string"},"customer_email":{"type":"string"},"delivery_address":{"type":"string"},"delivery_city":{"type":"string"},"delivery_area":{"type":"string"},"delivery_notes":{"type":"string"},"notes":{"type":"string"},"payment_status":{"type":"string","enum":["unpaid","paid","refunded"]},"estimated_prep_minutes":{"type":"integer"}}},"CreateOrderSuccess":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"orderger_order_id":{"type":"string"},"status":{"type":"string","enum":["pending_acceptance"]},"delivery_qr_url":{"type":"string","format":"uri"},"message":{"type":"string"}}},"ErrorResponse":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"},"message":{"type":"string"},"field":{"type":"string"}}},"InsufficientBalance":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"},{"type":"object","properties":{"error":{"type":"string","enum":["insufficient_balance"]},"top_up_required":{"type":"boolean","enum":[true]},"balance":{"type":"number"},"currency":{"type":"string"},"message_ar":{"type":"string"}}}]},"OrderStatus":{"type":"string","enum":["pending_acceptance","preparing","waiting_for_courier","on_the_way","delivered","rejected","cancelled"]},"Branch":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"phone":{"type":"string"},"address":{"type":"string"},"city":{"type":"string"},"enabled":{"type":"integer"}}},"InstallBundle":{"type":"object","properties":{"api_base":{"type":"string","format":"uri"},"business":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}}},"branches":{"type":"array","items":{"$ref":"#/components/schemas/Branch"}},"api_key":{"type":"string","description":"A freshly minted API key. Shown ONCE."},"webhook_secret":{"type":"string","description":"A freshly generated webhook signing secret."},"snippet":{"type":"object","description":"Stack-tailored code snippet (if ?stack=... was provided)."},"instructions":{"type":"string"}}}}},"x-orderger-webhooks":{"description":"OrderGer sends signed POST requests to your registered webhook URL when order status changes.","signature_header":"X-OrderGer-Signature: sha256=<hex>","algorithm":"HMAC-SHA256(rawBody, webhook_secret)","events":["order.created","order.accepted","order.preparing","order.waiting_for_courier","order.on_the_way","order.delivered","order.rejected","order.cancelled","order.updated"],"sample_payload":{"event":"order.accepted","orderger_order_id":"ord_xxx","external_order_id":"WEB-10052","business_id":"biz_xxx","branch_id":"branch_xxx","status":"preparing","timestamp":1782671913000},"retries":"Failed deliveries (non-2xx or timeout) are retried with exponential backoff up to 5 attempts."}}