🎉 Aerocall is now live! Start building →
E-commerceDeveloper Guide

E-commerce Developer Guide

This guide is for developers building storefronts or custom integrations with the Aerocall E-commerce API.

1. Authentication

The Public API is designed to be consumed directly from the browser (storefront).

API Keys

All requests should include your public API key in the Authorization header:

Authorization: Bearer <YOUR_PUBLIC_KEY>

You can find this key in the Project Settings > API Keys section of the dashboard.

2. API Overview

The base URL for all public e-commerce endpoints is: https://<project-slug>.aerocall.ai/api/v1/ecommerce

If you connect your own domain (for example https://shop.yourdomain.com) to the same project, the host changes but the paths stay the same:

https://shop.yourdomain.com/api/v1/ecommerce

Common Endpoints

MethodEndpointDescription
GET/productsList all active products. Supports filtering and pagination.
GET/products/:slugGet a single product by its URL slug.
GET/categoriesList all categories (tree structure).
GET/cart/:cartIdRetrieve a cart’s contents (or an empty cart if it does not exist yet).
POST/cart/:cartId/itemsAdd or increment an item in a cart (creates the cart if it does not exist).
POST/checkoutInitialize the checkout process for a given cart.
GET/orders/:idRetrieve a customer order by id (with email query parameter).

3. Handling Data

The API returns standard JSON responses. Errors follow the standard 4xx and 5xx status codes with a message field.

Pagination

List endpoints (like /products) support pagination query parameters:

  • page: Page number (default: 1).
  • limit: Items per page (default: 20).

Filtering

You can filter products by category or custom attributes:

  • category_id: Filter by specific category.
  • sort: Sort by price_asc, price_desc, created_at.

4. The Cart Flow

Managing a shopping cart involves maintaining a local reference to a server-side cart ID.

  1. Initialize: On first load, check localStorage for a cartId.
  2. Create ID (if needed): If no ID exists, generate a new cartId (for example a UUID) and store it in localStorage. There is no dedicated “create cart” endpoint; the first add will create it.
  3. Add/Update: Use POST /cart/:cartId/items with { productId, quantity, variantId }.
  4. Sync: Always update your local UI with the response from the cart endpoints, as they return the full calculated totals (including discounts and tax).

5. Checkout & Payments

Step 1: Validate Cart

Ensure the cart has items and valid quantities.

Step 2: Initialize Checkout

POST /checkout with:

  • cartId
  • customerEmail
  • shippingAddress (if applicable)

Response:

  • orderId: The draft order ID.
  • paymentIntent: (e.g., Stripe Client Secret) used to render the payment element.

Step 3: Confirm Payment

Use your payment provider’s SDK (e.g., Stripe.js) to confirm the payment using the client_secret.

Step 4: Verification

Once the payment is confirmed, the frontend can redirect to a “Thank You” page. The backend will receive a webhook from the provider and update the order status to paid asynchronously.

6. Webhooks

You can subscribe to events to trigger backend processes (e.g., sending an email, updating inventory in ERP).

  • order.created: Fired when a checkout is initialized.
  • order.paid: Fired when payment is confirmed.
  • order.shipped: Fired when an admin adds a tracking number.
  • inventory.low: (Optional) Fired when stock drops below threshold.

For E-commerce order webhooks, verify signatures using the X-Webhook-Signature: sha256=... header and read the event type from X-Webhook-Event to ensure authenticity.

Admin GuideStorefront Recipes