E-commerce Developer Guide

This guide is for developers building storefronts or custom integrations with the Aerostack 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 optionally pass the key as a query parameter: ?token=<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://api.aerostack.dev/api/v1/public/projects/{projectSlug}/ecommerce

Replace {projectSlug} with your project’s slug (e.g. my-store).

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

Endpoints Reference

Method	Endpoint	Description
`GET`	`/config`	Get store config (currency, tax, shipping, payment provider). No auth required.
`GET`	`/products`	List all active products. Supports filtering and pagination.
`GET`	`/products/:slug`	Get a single product by its URL slug.
`GET`	`/categories`	List all categories (tree structure).
`GET`	`/cart/:cartId`	Retrieve a cart’s contents (or an empty cart if it does not exist yet).
`POST`	`/cart/:cartId/items`	Add or increment an item in a cart (creates the cart if it does not exist).
`PATCH`	`/cart/:cartId/items/:itemId`	Update item quantity.
`DELETE`	`/cart/:cartId/items/:itemId`	Remove item from cart.
`DELETE`	`/cart/:cartId`	Clear the entire cart.
`POST`	`/coupons/validate`	Validate a coupon code.
`POST`	`/checkout`	Initialize checkout and create order. Returns payment session for Stripe/Razorpay.
`GET`	`/orders`	List customer orders by email (query: `?email=...`).
`GET`	`/orders/:id`	Retrieve a single order by id (query: `?email=...` required).

3. Store Config

Before building your checkout UI, fetch the store configuration:

GET /config

Response:

{
  "default_currency": "USD",
  "currency_symbol": "$",
  "tax_percentage": 10,
  "flat_shipping_rate": 5,
  "free_shipping_threshold": 100,
  "shipping_enabled": true,
  "payment_provider": "stripe"
}

Use this to display currency, calculate taxes, show shipping options, and determine which payment flow to use (Stripe, Razorpay, or manual/COD).

4. The Cart Flow

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

Initialize: On first load, check localStorage for a cartId.
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.
Add/Update: Use POST /cart/:cartId/items with { productId, quantity, variantId }.
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": "your-cart-id",
  "email": "[email protected]",
  "shippingAddress": { "line1": "123 Main St", "city": "City", "postal_code": "12345", "country": "US" },
  "billingAddress": { "line1": "123 Main St", "city": "City", "postal_code": "12345", "country": "US" },
  "couponCode": "SAVE10",
  "customerName": "John Doe",
  "customerPhone": "+1234567890",
  "successUrl": "https://yoursite.com/order/success",
  "cancelUrl": "https://yoursite.com/cart"
}

Address schema (optional): line1, line2, city, state, postal_code, country

Response:

{
  "success": true,
  "order": { "id": "...", "order_number": "ORD-001", "grand_total": 29.99 },
  "payment": {
    "id": "cs_...",
    "url": "https://checkout.stripe.com/..."
  }
}

For Stripe: redirect the user to payment.url.

For Razorpay: payment includes:

token (key_id) – load Razorpay.js with this
providerOrderId – Razorpay order ID
amount – amount in smallest unit (paise/cents)
currency – e.g. “USD”, “INR”

Open the Razorpay checkout modal with these values.

Step 3: Success / Cancel URLs

You can pass optional successUrl and cancelUrl in the checkout body. If omitted, defaults point to the Aerostack-hosted storefront.

Step 4: Verification

Once payment is confirmed, the backend receives a webhook from Stripe/Razorpay and updates the order status to paid. Redirect the user to your success page — the order confirmation email is sent automatically.

6. Order History

To show “My Orders” for a customer:

GET /[email protected]&page=1&limit=20

Response:

{
  "orders": [
    { "id": "...", "order_number": "ORD-001", "status": "processing", "payment_status": "paid", "currency": "USD", "grand_total": 29.99, "created_at": 1707753600000 }
  ],
  "total": 10,
  "page": 1,
  "limit": 20
}

To fetch a single order (e.g. order confirmation page):

GET /orders/:[email protected]

7. Webhooks

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

Event	When
`order.created`	Checkout is initialized.
`order.paid`	Payment is confirmed by Stripe/Razorpay.
`order.shipped`	Admin adds a tracking number.
`inventory.low`	(Optional) 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.

8. Amount Format (Stripe / Razorpay)

Both Stripe and Razorpay expect amounts in smallest currency unit (cents for USD, paise for INR). The API handles this internally — amounts in checkout and order responses are in main units (e.g. 29.99 USD). The payment session response for Razorpay includes amount already in smallest unit for the Razorpay.js modal.

Admin Guide Storefront Recipes