API Reference

REST API for programmatic access to your store

Authentication

All API requests require authentication using an API key.

Getting Your API Key

1. Go to Settings → API
2. Click Generate API Key
3. Copy and securely store your key

Using Your API Key

Include your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Example Request

curl -X GET "https://api.beava.ca/v1/products" \
  -H "Authorization: Bearer sk_live_abc123..." \
  -H "Content-Type: application/json"

Base URL

https://api.beava.ca/v1/

Products API

GET /products

List all products

{
  "products": [
    {
      "id": "prod_abc123",
      "title": "Beeswax Candle",
      "description": "Natural beeswax candle",
      "price": 24.99,
      "compare_at_price": 29.99,
      "sku": "BWC-001",
      "inventory_quantity": 50,
      "status": "active",
      "images": ["https://..."],
      "created_at": "2024-01-15T10:30:00Z"
    }
  ],
  "total": 150,
  "page": 1,
  "per_page": 20
}

GET /products/{id}

Get a single product by ID

POST /products

Create a new product

PUT /products/{id}

Update an existing product

DELETE /products/{id}

Delete a product

Orders API

GET /orders

List all orders

{
  "orders": [
    {
      "id": "ord_xyz789",
      "order_number": "1001",
      "status": "processing",
      "total": 74.97,
      "subtotal": 69.97,
      "shipping": 5.00,
      "tax": 0.00,
      "customer": {
        "email": "customer@example.com",
        "name": "John Doe"
      },
      "line_items": [
        {
          "product_id": "prod_abc123",
          "title": "Beeswax Candle",
          "quantity": 3,
          "price": 24.99
        }
      ],
      "shipping_address": {...},
      "created_at": "2024-01-20T14:22:00Z"
    }
  ],
  "total": 523,
  "page": 1
}

GET /orders/{id}

Get a single order

PUT /orders/{id}

Update order (status, notes, tracking)

Inventory API

GET /inventory

Get inventory levels for all products

POST /inventory/adjust

Adjust inventory levels

{
  "product_id": "prod_abc123",
  "adjustment": -5,
  "reason": "Damaged items"
}

GET /inventory/low-stock

Get products below low stock threshold

Customers API

GET /customers

List all customers

GET /customers/{id}

Get customer details including order history

GET /customers/{id}/orders

Get all orders for a customer

Webhooks

Receive real-time notifications for events in your store.

Available Events

• order.created — New order placed
• order.updated — Order status changed
• order.fulfilled — Order shipped
• payment.completed — Payment received
• payment.refunded — Refund processed
• product.created — New product added
• product.updated — Product modified
• inventory.low — Stock below threshold

Webhook Payload

{
  "event": "order.created",
  "timestamp": "2024-01-20T14:22:00Z",
  "data": {
    "id": "ord_xyz789",
    "order_number": "1001",
    ...
  }
}

Configuring Webhooks

1. Go to Settings → API → Webhooks
2. Click Add Webhook
3. Enter your endpoint URL
4. Select events to subscribe to
5. Save and test

Rate Limits

• Standard: 100 requests per minute
• Burst: Up to 20 requests per second

Rate limit headers are included in responses:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1705764120

Error Handling

Errors return appropriate HTTP status codes:

• 400 — Bad request (invalid parameters)
• 401 — Unauthorized (invalid API key)
• 403 — Forbidden (insufficient permissions)
• 404 — Not found
• 429 — Rate limit exceeded
• 500 — Server error

{
  "error": {
    "code": "invalid_parameter",
    "message": "Price must be a positive number",
    "field": "price"
  }
}