Store API — Connect Your Online Store to Botaura

Overview

The Store API lets you connect any online store (WooCommerce, Shopify, custom) to Botaura. Once connected, your customers automatically receive WhatsApp order confirmations with Confirm / Cancel buttons, and you can manage orders from the Botaura dashboard or programmatically via the API.

Plan requirement: The Store API is available on the Business plan ($10/mo). Free and Pro plans will receive a 403 error.

---

Quick Start

1. Go to Dashboard → Settings → Integrations
2. Click Generate API Key — copy and store it securely
3. Send order events to https://botaura.app/api/v1/events/ingest

Send Your First Order

curl -X POST https://botaura.app/api/v1/events/ingest \
  -H "Content-Type: application/json" \
  -H "X-Botaura-Key: YOUR_API_KEY" \
  -d '{
    "event_type": "order_created",
    "idempotency_key": "order-abc-123",
    "customer": {
      "phone": "923001234567",
      "name": "Ali Khan",
      "consent": true
    },
    "order": {
      "items": [
        { "name": "Widget Pro", "qty": 2, "price": 1500 }
      ],
      "total": 3000,
      "external_order_id": "WC-456"
    }
  }'

If consent is true and the customer has a WhatsApp number, they'll receive a Confirm / Cancel message automatically. The same idempotency_key won't create a duplicate order.

---

Authentication

All Store API requests require the X-Botaura-Key header with your API key. The key is hashed (SHA-256) on our side — we never store your raw key.

• Missing key → 401 Unauthorized
• Invalid key → 401 Unauthorized
• Wrong plan → 403 Forbidden
• Rate limit → 429 Too Many Requests (60 requests/hour)

---

API Endpoints

1. Ingest an Order

POST /api/v1/events/ingest

Send an order event from your store. Botaura creates the order, sends a WhatsApp confirmation to the customer, and fires any configured webhooks.

Request body:

{
  "event_type": "order_created",
  "idempotency_key": "unique-key-per-order",
  "customer": {
    "phone": "923001234567",
    "name": "Customer Name",
    "consent": true
  },
  "order": {
    "items": [
      { "name": "Product Name", "qty": 1, "price": 500 }
    ],
    "total": 500,
    "external_order_id": "YOUR-ORDER-ID"
  }
}

2. List Orders

GET /api/v1/orders

Returns a paginated list of your business orders.

Query parameters:

• status — Filter by status: pending, confirmed, shipped, delivered, cancelled
• source — Filter by source: whatsapp, ingest
• limit — Results per page (1–200, default 50)
• offset — Skip N results (default 0)

Response:

{
  "orders": [ ... ],
  "total": 42,
  "limit": 50,
  "offset": 0
}

3. Get Order Detail

GET /api/v1/orders/:id

Returns full order details including line items and customer information.

4. Update Order Status

PATCH /api/v1/orders/:id/status

Update the status of an order. Valid transitions follow the FSM:

• pending → confirmed or cancelled
• confirmed → shipped or cancelled
• shipped → delivered

Request body:

{ "status": "confirmed" }

When you update the status, the customer receives a WhatsApp notification automatically.

---

Reverse Webhooks

Get real-time callbacks when orders are created or their status changes. Botaura sends a POST request to your endpoint with the event payload.

Setup

1. Go to Dashboard → Settings → Integrations → Reverse Webhooks
2. Click Add Endpoint
3. Enter your webhook URL and select which events to subscribe to
4. Copy the signing secret — it's shown only once

Or configure via the API:

# Create a webhook endpoint
curl -X POST https://botaura.app/api/v1/webhooks \
  -H "X-Botaura-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-store.com/webhooks/botaura",
    "events": ["order_created", "order_status_changed"]
  }'

Event Types

• order_created — Fired when an order is ingested via the Store API
• order_status_changed — Fired when an order status is updated

Payload Format

{
  "event": "order_created",
  "timestamp": "2026-06-18T12:00:00Z",
  "data": {
    "order_id": "...",
    "order_number": "ORD-001",
    "status": "pending",
    "total": 3000,
    "customer_phone": "923001234567",
    "source": "ingest"
  }
}

Verifying Signatures

Every webhook request includes an X-Botaura-Signature header. Verify it by computing HMAC-SHA256 of the raw request body using your signing secret:

import hmac, hashlib

def verify_signature(body: bytes, signature: str, secret: str) -> bool:
    expected = "sha256=" + hmac.new(
        secret.encode(), body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

Retry Policy

• Failed deliveries retry 3 times with exponential backoff (1s, 4s, 16s)
• After 10 consecutive failures, the endpoint is automatically deactivated
• You can re-activate it from the dashboard or API

---

Managing Webhooks via API

• GET /api/v1/webhooks — List all your webhook endpoints
• POST /api/v1/webhooks — Create a new endpoint (max 5 per business)
• PATCH /api/v1/webhooks/:id — Update URL, events, or active status
• DELETE /api/v1/webhooks/:id — Remove an endpoint

---

Rate Limits

The Store API allows 60 requests per hour per business. If you exceed this, you'll receive a 429 response. The limit resets every hour.

---

Error Codes

Code	Meaning
400	Invalid request body or parameters
401	Missing or invalid API key
403	Plan doesn't support Store API (upgrade to Business)
404	Order or webhook endpoint not found
409	Duplicate idempotency key (order already exists)
429	Rate limit exceeded
500	Internal server error

---

Need Help?

If you're having trouble integrating, chat with Aura (our AI assistant) for instant help, or contact us at support@botaura.com.