API Documentation · Version 1.1

Connect your systems to Owncart ordering

Let your POS, app, chatbot or website read live menus, create carts, collect payments and follow every order — all through one secure connection.

Download PDF DocumentationExplore Endpoints ↓
Base Addressbackend3.owct.me
Payload FormatHTTPS POST · JSON
Rate Limits60 Orders / hr
AuthenticationKey + Secret Header
HomeIntegrationsAPI Documentation
Overview

Connect Your Systems to Owncart Ordering

The Owncart API is a secure server-to-server connection that lets your POS, mobile app, kiosk, chatbot or call centre interact with a store's Owncart account without manual menu re-entry or order re-typing.

01

Store Owner Controls Access

API keys are generated inside the Owncart Admin panel (Settings → API Keys). Secrets are visible once.

Admin Panel · 1-Time Secret
02

Granular Permissions

Each key is constrained to specific roles — such as "read menu" or "create orders" — and nothing else.

Role-Based · Scoped Keys
03

Encrypted & One Store Only

All traffic runs over HTTPS. Keys strictly access the tenant that generated them, isolated from other stores.

TLS 1.3 · Tenant Isolated
Security & Authentication

Headers on Every Request

Every API request must carry your store's API Key and Secret. Call the API strictly from your backend server — never expose credentials in front-end JavaScript or client mobile apps.

Required HTTP Headers
OWNCART-API-KEY: <your key>
OWNCART-API-SECRET: <your secret>
Content-Type: application/json

Rate Limits & Safeguards

Checkout endpoints are rate-limited to 60 orders / hour and 50 payment attempts / 15 minutes per store to eliminate bot spam. Exceeding thresholds returns an HTTP 429 Too Many Requests with a RateLimit-Reset header.

Code Snippet Language:
POST/item/list?page=1&limit=50
Requires: Menu → Read

Get Full Menu Items

Lists every item with its price, sizes, add-ons, photos and whether it is in stock — including items currently switched off.

Use it for: Syncing a POS or kiosk menu, showing a store's items in an app or digital catalog.
Request Body Parameters
FieldTypeDescription
outletId*requiredstringBranch identifier shared during store onboarding
categoryIdoptionalstringFilter items by a specific category ID
searchTextoptionalstringSearch term to match dish or item name (e.g. 'dosa')
inStockoptionalbooleanFilter strictly for currently available items
curl -X POST "https://backend3.owct.me/item/list?page=1&limit=50" \
  -H "OWNCART-API-KEY: your_api_key_here" \
  -H "OWNCART-API-SECRET: your_api_secret_here" \
  -H "Content-Type: application/json" \
  -d '{
  "outletId": "<outlet id>",
  "categoryId": "<optional>",
  "searchText": "dosa",
  "inStock": true
}'
POST/table/get-all?page=1&limit=50
Requires: Menu → Read

Get Dine-in Tables

Lists all configured dine-in tables for an outlet.

Use it for: Table ordering, floor layout sync, and QR stand validation.
Request Body Parameters
FieldTypeDescription
outletId*requiredstringBranch identifier
activeOnlyoptionalbooleanReturn only active dining tables
curl -X POST "https://backend3.owct.me/table/get-all?page=1&limit=50" \
  -H "OWNCART-API-KEY: your_api_key_here" \
  -H "OWNCART-API-SECRET: your_api_secret_here" \
  -H "Content-Type: application/json" \
  -d '{
  "outletId": "<outlet id>",
  "activeOnly": true
}'
POST/apis/customer/login
Requires: Customer → Create

Customer Lookup & WhatsApp Login

Recognises a customer by mobile number (creates their profile if new) and generates a one-tap sign-in link. Can also dispatch the link or an OTP to their WhatsApp.

Use it for: Chatbots, call centres, or 'Continue on website' flows in apps.
Note: The returned URL signs the customer directly in. Only transmit it to the intended recipient.
Request Body Parameters
FieldTypeDescription
phone*requiredstringMobile number with country code (e.g. '919876543210')
nameoptionalstringCustomer full name
mode*requiredstring'whatsapp' = return link only; 'web' = dispatch on WhatsApp; 'otp' = send OTP code
curl -X POST "https://backend3.owct.me/apis/customer/login" \
  -H "OWNCART-API-KEY: your_api_key_here" \
  -H "OWNCART-API-SECRET: your_api_secret_here" \
  -H "Content-Type: application/json" \
  -d '{
  "phone": "919876543210",
  "name": "Ravi",
  "mode": "whatsapp"
}'
POST/customer/get-addresses
Requires: Customer → Read

Get Saved Addresses

Lists saved delivery addresses for a customer so they never need to re-type them.

Use it for: Faster checkout in mobile apps, chatbots, and CRM repeat orders.
Request Body Parameters
FieldTypeDescription
customerPhoneNo*requiredstringMobile number with country code
outletId*requiredstringOutlet identifier
curl -X POST "https://backend3.owct.me/customer/get-addresses" \
  -H "OWNCART-API-KEY: your_api_key_here" \
  -H "OWNCART-API-SECRET: your_api_secret_here" \
  -H "Content-Type: application/json" \
  -d '{
  "customerPhoneNo": "919876543210",
  "outletId": "<outlet id>"
}'
POST/cart/create
Requires: Order → Create

Start a Cart

Creates an active cart with selected items and order type ('Door Delivery', 'Self Pickup', or 'Dine In'). Keep the returned orderId for subsequent actions.

Use it for: Initiating checkout from a mobile app, voice assistant, kiosk, or chatbot.
Request Body Parameters
FieldTypeDescription
customerPhoneNo*requiredstringMobile number with country code
customerName*requiredstringCustomer name
outletId*requiredstringTarget outlet identifier
deliveryType*requiredstring'Door Delivery' | 'Self Pickup' | 'Dine In'
items*requiredarrayArray of items with itemId, quantity, and optional variationId
addressIdoptionalstringSaved address ID (or pass address1, city, state, pincode, lat, lng)
tableIdoptionalstringTable identifier (Required for Dine In)
curl -X POST "https://backend3.owct.me/cart/create" \
  -H "OWNCART-API-KEY: your_api_key_here" \
  -H "OWNCART-API-SECRET: your_api_secret_here" \
  -H "Content-Type: application/json" \
  -d '{
  "customerPhoneNo": "919876543210",
  "customerName": "Ravi",
  "outletId": "<outlet id>",
  "deliveryType": "Door Delivery",
  "items": [
    {
      "itemId": "<item id>",
      "quantity": 2,
      "variationId": "<optional>"
    }
  ],
  "addressId": "<saved address id>"
}'
POST/cart/update
Requires: Order → Update

Change Cart Contents

Add or remove items, adjust quantities, switch fulfillment between delivery, pickup and dine-in, or change the address. Always send the full updated item list.

Use it for: 'Add one more dish', 'switch to pickup', modifying cart before checkout.
Request Body Parameters
FieldTypeDescription
orderId*requiredstringCart / order ID returned from /cart/create
outletId*requiredstringOutlet identifier
customerPhoneNo*requiredstringCustomer mobile number
deliveryType*requiredstringUpdated fulfillment type
items*requiredarrayComplete array of updated items
curl -X POST "https://backend3.owct.me/cart/update" \
  -H "OWNCART-API-KEY: your_api_key_here" \
  -H "OWNCART-API-SECRET: your_api_secret_here" \
  -H "Content-Type: application/json" \
  -d '{
  "orderId": "<cart id>",
  "outletId": "<outlet id>",
  "customerPhoneNo": "919876543210",
  "deliveryType": "Self Pickup",
  "items": [
    {
      "itemId": "<item id>",
      "quantity": 3
    }
  ]
}'
POST/cart/get-cart-details
Requires: Order → Read

Get Cart Details & Live Total

Returns the open cart with calculated tax, discount rules, delivery charges, real-time stock availability, and checkout eligibility.

Use it for: Displaying order breakdown, review screen, and checking minimum order limits.
Request Body Parameters
FieldTypeDescription
outletId*requiredstringOutlet identifier
customerPhoneNo*requiredstringCustomer mobile number
orderId*requiredstringCart / order ID
curl -X POST "https://backend3.owct.me/cart/get-cart-details" \
  -H "OWNCART-API-KEY: your_api_key_here" \
  -H "OWNCART-API-SECRET: your_api_secret_here" \
  -H "Content-Type: application/json" \
  -d '{
  "outletId": "<outlet id>",
  "customerPhoneNo": "919876543210",
  "orderId": "<cart id>"
}'
POST/cart/update-payment-mode
Requires: Order → Update

Select Payment Mode

Configures whether the order will be settled via Cash on Delivery ('COD') or an online payment gateway configured for the store.

Use it for: Payment selection radio buttons during checkout.
Request Body Parameters
FieldTypeDescription
outletId*requiredstringOutlet identifier
orderId*requiredstringCart / order ID
customerPhoneNo*requiredstringCustomer mobile number
paymentMode*requiredstring'COD' | 'ONLINE'
curl -X POST "https://backend3.owct.me/cart/update-payment-mode" \
  -H "OWNCART-API-KEY: your_api_key_here" \
  -H "OWNCART-API-SECRET: your_api_secret_here" \
  -H "Content-Type: application/json" \
  -d '{
  "outletId": "<outlet id>",
  "orderId": "<cart id>",
  "customerPhoneNo": "919876543210",
  "paymentMode": "COD"
}'
POST/cart/order-checkout
Requires: Payment → Create

Place Order / Generate Payment Link

For COD: order is confirmed immediately. For online payment: returns payment links or gateway credentials (Razorpay, Stripe, Shopify Draft Order) and confirms once payment succeeds.

Use it for: Final 'Place Order' or 'Pay Now' submission button.
Request Body Parameters
FieldTypeDescription
orderId*requiredstringCart / order ID
outletId*requiredstringOutlet identifier
customerPhoneNo*requiredstringCustomer mobile number
paymentMode*requiredstring'COD' or payment provider
curl -X POST "https://backend3.owct.me/cart/order-checkout" \
  -H "OWNCART-API-KEY: your_api_key_here" \
  -H "OWNCART-API-SECRET: your_api_secret_here" \
  -H "Content-Type: application/json" \
  -d '{
  "orderId": "<cart id>",
  "outletId": "<outlet id>",
  "customerPhoneNo": "919876543210",
  "paymentMode": "COD"
}'
POST/apis/orders/get-order-details
Requires: Order → Read

Get Order Details & Status

Fetches full details of a specific order including line items, subtotal, taxes, payment mode, delivery address, and live status (Accepted, Preparing, Out for delivery, Delivered).

Use it for: Order tracking screens, kitchen KOT display, and customer support lookups.
Request Body Parameters
FieldTypeDescription
orderId*requiredstringConfirmed order identifier
outletId*requiredstringOutlet identifier
curl -X POST "https://backend3.owct.me/apis/orders/get-order-details" \
  -H "OWNCART-API-KEY: your_api_key_here" \
  -H "OWNCART-API-SECRET: your_api_secret_here" \
  -H "Content-Type: application/json" \
  -d '{
  "orderId": "<order id>",
  "outletId": "<outlet id>"
}'
POST/apis/orders/get-last-order-details
Requires: Order → Read

Get Customer's Latest Order

Retrieves the most recent order placed by a customer at a given outlet.

Use it for: Chatbot 'Where is my order?' queries and 'Repeat previous order' buttons.
Request Body Parameters
FieldTypeDescription
customerId*requiredstringCustomer identifier
outletId*requiredstringOutlet identifier
curl -X POST "https://backend3.owct.me/apis/orders/get-last-order-details" \
  -H "OWNCART-API-KEY: your_api_key_here" \
  -H "OWNCART-API-SECRET: your_api_secret_here" \
  -H "Content-Type: application/json" \
  -d '{
  "customerId": "<customer id>",
  "outletId": "<outlet id>"
}'
POST/apis/orders/get-orders
Requires: Order → Read

List Orders

Returns a paginated list of orders filtered by outlet and/or customer ID.

Use it for: Order history screens, daily reconciliation, and store reporting.
Request Body Parameters
FieldTypeDescription
outletId*requiredstringFilter by outlet
customerIdoptionalstringFilter by customer ID
curl -X POST "https://backend3.owct.me/apis/orders/get-orders" \
  -H "OWNCART-API-KEY: your_api_key_here" \
  -H "OWNCART-API-SECRET: your_api_secret_here" \
  -H "Content-Type: application/json" \
  -d '{
  "outletId": "<outlet id>",
  "customerId": "<optional>"
}'
Instant Updates

Webhooks (Real-Time Push Notifications)

Owncart calls your HTTPS server automatically whenever an event occurs, eliminating the need for polling. Configure your webhook URL in the Admin Panel under Settings → Webhook.

order_createdA new order is successfully placed
order_statusOrder progresses (Accepted, Preparing, Ready, Out for delivery, Delivered)
delivery_statusDelivery partner updates trip or rider location
order_cancelAn order is cancelled
order_returnAn order is marked returned
abandoned_cartA customer left items in cart without completing checkout
cart_payment_cancelAn online payment was abandoned or failed
store_closed_visitorA customer visited store ordering while outlet was closed
Webhook Payload Example: order_status
{
  "orderId": "<order id>",
  "status": "Out for delivery",
  "orderTotal": 313.9,
  "customerName": "Ravi",
  "customerPhoneNo": "919876543210",
  "trackingUrl": "https://owncart.ai/track/..."
}

Webhook Best Practice: Return an HTTP 200 OK immediately. Each event is dispatched once. Confirm order details with /apis/orders/get-order-details before taking critical kitchen or dispatch actions, and design handlers to be idempotent.

Status & Errors

HTTP Error Codes Reference

Standard HTTP status codes are returned with descriptive error messages in the JSON payload.

StatusMeaning & Resolution
400Missing or invalid parameter, or business rule validation (outside delivery radius, below minimum order value, expired promo code). Read message.
401API Key or Secret missing, invalid, or disabled in Admin panel.
403The key lacks permission for this endpoint (see details.requiredScreen / requiredAccess).
409Conflict error (e.g. code: "STOCK") — an item just sold out before checkout completion.
422Field validation failed. Specific problem fields are enumerated line-by-line in message.
429Rate limit exceeded (>60 orders/hr or >50 checkout attempts/15 min). Retry after RateLimit-Reset timestamp.
5xxTransient server or payment gateway communication error. Safe to retry with exponential backoff.

Ready to Integrate Your POS or App?

Contact your iEYAL Solutions account manager to receive a dedicated sandbox test store and outlet credentials. Our technical team assists throughout your integration.

Book demoStart free