Byserva Public API Documentation

Overview of Byserva API

Welcome to the Byserva Public API documentation! This API provides a robust and flexible solution for building custom e-commerce storefronts, acting as a powerful headless commerce platform. Whether you're looking for a Shopify alternative, need to integrate e-commerce functionalities into an existing application, or want complete control over your frontend, Byserva API has you covered.

The API is built on Cloudflare Workers for high performance and scalability, offering endpoints to manage your store's products, collections, validate customer carts, and send important notifications. It's designed to be lightweight, fast, and easy to integrate into any modern web application.

With Byserva, you can focus on creating unique and engaging user experiences, while we handle the backend commerce logic.

API Root URL

All requests to the Byserva Public API should be made to the following base URL:

https://api.byserva.com

Obtaining Your Store ID

To interact with your store's data, you will need a unique Store ID. This ID acts as the primary identifier for all your API requests, ensuring you access the correct store's resources.

Steps to Get Your Store ID:

Sign up or Log in: Go to the Byserva Dashboard and either create a new account or log into your existing one.
Create a Store: If you don't already have one, create a new store within your Byserva dashboard.
Navigate to Settings: Once your store is created and selected, go to the Settings section of your dashboard.
Locate Store ID: Your unique Store ID will be prominently displayed there. Copy this ID; you will use it in all your API requests.

All products and collections can be created, edited, and managed directly via the Byserva dashboard, ensuring a seamless content management experience.

For demonstration purposes, we will use the example Store ID: 1457FPTZD.

Basic Request Structure

All Byserva API endpoints follow a consistent URL structure:

https://api.byserva.com/{storeId}/{resource}/{subResource?}

{storeId}: Your unique Byserva Store ID (e.g., 1457FPTZD).
{resource}: The API resource you want to access (e.g., products, collections, validate, notify).
{subResource?}: An optional identifier for a specific item within the resource (e.g., a product ID or collection ID).

CORS Policy

The Byserva Public API is designed with frontend applications in mind. It fully supports Cross-Origin Resource Sharing (CORS), meaning you can make direct API calls from your web browser without encountering CORS-related errors.

The following CORS headers are always included in responses:

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, OPTIONS
Access-Control-Allow-Headers: Content-Type, Authorization

Detailed API Endpoints

Products API

The Products API allows you to retrieve detailed information about the products available in your Byserva store. You can fetch a list of all products or retrieve a specific product by its ID.

1. Get All Products

Retrieves a list of all products from your store.

Endpoint: GET /{storeId}/products
Query Parameters:
- sort: Sorts products by price. Accepted values: price_asc, price_desc.
- pg: Paginates results. Format: start-end (e.g., 1-10 for the first 10 items).
- limit: Limits the number of results returned (e.g., 5).

Example Request (List all products, sorted by price ascending, limit 2)

curl -X GET "https://api.byserva.com/1457FPTZD/products?sort=price_asc&limit=2"

fetch('https://api.byserva.com/1457FPTZD/products?sort=price_asc&limit=2')
  .then(response => response.json())
  .then(data => console.log(data))
  .catch(error => console.error('Error:', error));

Example Response (200 OK)

[
  {
    "id": "-OnE63diwuHJByfM7svB",
    "coll": "XOXO Donuts",
    "desc": "",
    "images": [
      "https://lsfloqowfyeophmotqrk.supabase.co/storage/v1/object/public/Byserva/products/1457FPTZD/1773105587983_0.06200572113422705.jpg"
    ],
    "name": "Pompom",
    "price": "1000",
    "qty": "12"
  },
  {
    "id": "-OnKKLz_dA38YOm-uhYp",
    "coll": "XOXO Donuts",
    "desc": "Buttery creamy delight.",
    "images": [
      "https://lsfloqowfyeophmotqrk.supabase.co/storage/v1/object/public/Byserva/products/1457FPTZD/1773105668547_0.3469806698670036.jpeg"
    ],
    "name": "XO Glaze",
    "price": "6000",
    "qty": "10"
  }
]

2. Get a Single Product by ID

Retrieves details for a specific product using its unique ID.

Endpoint: GET /{storeId}/products/{productId}
Path Parameters:
- {productId}: The unique ID of the product (e.g., -OnE63diwuHJByfM7svB).

Example Request (Get product 'Pompom')

curl -X GET "https://api.byserva.com/1457FPTZD/products/-OnE63diwuHJByfM7svB"

Example Response (200 OK)

{
  "id": "-OnE63diwuHJByfM7svB",
  "coll": "XOXO Donuts",
  "desc": "",
  "images": [
    "https://lsfloqowfyeophmotqrk.supabase.co/storage/v1/object/public/Byserva/products/1457FPTZD/1773105587983_0.06200572113422705.jpg"
  ],
  "name": "Pompom",
  "price": "1000",
  "qty": "12"
}

Collections API

The Collections API allows you to retrieve information about your product collections. You can fetch a list of all collections or retrieve a specific collection, optionally including its associated products.

1. Get All Collections

Retrieves a list of all collections defined in your store.

Endpoint: GET /{storeId}/collections
Query Parameters: None specific to listing collections directly.

Example Request (List all collections)

curl -X GET "https://api.byserva.com/1457FPTZD/collections"

Example Response (200 OK)

[
  {
    "id": "-OnKCr5DRhsAQW4r-FD0",
    "img": "https://lsfloqowfyeophmotqrk.supabase.co/storage/v1/object/public/Byserva/collections/1457FPTZD/1773103702972_0.7799912141817446.jpg",
    "name": "XOXO Donuts"
  },
  {
    "id": "-OnKCwSCun9ES3B862Os",
    "img": "https://lsfloqowfyeophmotqrk.supabase.co/storage/v1/object/public/Byserva/collections/1457FPTZD/1773103724407_0.6680997710387759.jpeg",
    "name": "Crunchies"
  }
]

2. Get a Single Collection with Products

Retrieves details for a specific collection and includes all products associated with it.

Endpoint: GET /{storeId}/collections/{collectionId}
Path Parameters:
- {collectionId}: The unique ID of the collection (e.g., -OnKCr5DRhsAQW4r-FD0 for "XOXO Donuts").
Query Parameters (for nested products):
- sort: Sorts products by price. Accepted values: price_asc, price_desc.
- pg: Paginates results. Format: start-end.
- limit: Limits the number of products returned.
Important Note: Products are linked to collections by their coll field matching the collection's name property (case-sensitive).

Example Request (Get 'XOXO Donuts' collection with products)

curl -X GET "https://api.byserva.com/1457FPTZD/collections/-OnKCr5DRhsAQW4r-FD0"

Example Response (200 OK)

{
  "img": "https://lsfloqowfyeophmotqrk.supabase.co/storage/v1/object/public/Byserva/collections/1457FPTZD/1773103702972_0.7799912141817446.jpg",
  "name": "XOXO Donuts",
  "id": "-OnKCr5DRhsAQW4r-FD0",
  "products": [
    {
      "id": "-OnE63diwuHJByfM7svB",
      "coll": "XOXO Donuts",
      "desc": "",
      "images": [
        "https://lsfloqowfyeophmotqrk.supabase.co/storage/v1/object/public/Byserva/products/1457FPTZD/1773105587983_0.06200572113422705.jpg"
      ],
      "name": "Pompom",
      "price": "1000",
      "qty": "12"
    },
    {
      "id": "-OnKKLz_dA38YOm-uhYp",
      "coll": "XOXO Donuts",
      "desc": "Buttery creamy delight.",
      "images": [
        "https://lsfloqowfyeophmotqrk.supabase.co/storage/v1/object/public/Byserva/products/1457FPTZD/1773105668547_0.3469806698670036.jpeg"
      ],
      "name": "XO Glaze",
      "price": "6000",
      "qty": "10"
    }
  ]
}

Validation API

The Validation API provides a critical server-side check for your customer's cart. It verifies the existence of products and the accuracy of prices, preventing discrepancies and potential fraud. This is essential before processing any payment.

1. Validate Cart Items and Total

Sends a list of items and a client-side calculated cart total to the server for validation against current product data.

Endpoint: POST /{storeId}/validate
Request Body (JSON):
```
{
  "items": [
    { "product_id": "string", "qty": "integer" },
    { "product_id": "string", "qty": "integer" }
  ],
  "cart_total": "number"
}
```
- items: An array of objects, each containing product_id and qty.
- cart_total: The total value of the cart as calculated by the client.

Example Request (Validate a cart with demo products)

Assuming "Pompom" (ID: `-OnE63diwuHJByfM7svB`, Price: `1000`) and "XO Glaze" (ID: `-OnKKLz_dA38YOm-uhYp`, Price: `6000`). A cart with 2 Pompom and 1 XO Glaze would have a total of `(2 * 1000) + (1 * 6000) = 8000`.

curl -X POST "https://api.byserva.com/1457FPTZD/validate" \
     -H "Content-Type: application/json" \
     -d '{
           "items": [
             { "product_id": "-OnE63diwuHJByfM7svB", "qty": 2 },
             { "product_id": "-OnKKLz_dA38YOm-uhYp", "qty": 1 }
           ],
           "cart_total": 8000
         }'

Example Response (200 OK - Valid Cart)

{
  "valid": true,
  "validationId": "val_1701234567890_abcde",
  "verified_total": 8000
}

Example Response (400 Bad Request - Product Missing)

{
  "error": "Product validation failed: prod_nonexistent_id missing.",
  "success": false
}

Example Response (409 Conflict - Price Mismatch)

{
  "error": "Price mismatch. Server: 8000, Client: 7500",
  "success": false
}

Notify API

The Notify API allows you to send various types of notifications, including emails, directly from your Byserva store. This can be used for order confirmations, marketing emails, customer service alerts, or any custom communication needs.

1. Send a Notification / Email

Sends a message and optionally an email to a specified recipient.

Endpoint: POST /{storeId}/notify
Request Body (JSON):
```
{
  "message": "string",
  "type": "string", // Optional: e.g., "Order Confirmation", "Marketing", "General"
  "email": {
    "to_email": "string",
    "subject": "string", // Optional
    "html": "string"     // Optional: HTML body for the email. If not provided, 'message' will be used as plain text.
  }
}
```
- message: The primary message content. Required.
- type: Categorizes the notification. Defaults to "General" if not provided.
- email.to_email: The recipient's email address. Required.
- email.subject: The subject line for the email. Defaults to "New Notification".
- email.html: The HTML content for the email body. If omitted, `message` is sent as plain text.

Example Request (Send an order confirmation email)

curl -X POST "https://api.byserva.com/1457FPTZD/notify" \
     -H "Content-Type: application/json" \
     -d '{
           "message": "Your order #12345 has been confirmed!",
           "type": "Order Confirmation",
           "email": {
             "to_email": "customer@example.com",
             "subject": "Order Confirmation for Byserva Store",
             "html": "Dear Customer,
Your order #12345 has been confirmed.
Thank you for shopping with us!"
           }
         }'

Example Response (200 OK)

{
  "success": true,
  "notificationId": "notif_1701234567890"
}

Example Response (400 Bad Request - Missing Fields)

{
  "error": "Missing required fields: message or email.to_email",
  "success": false
}

General Query Parameters & Filters

Several endpoints (Products API, and nested products within Collections API) support common query parameters for filtering and ordering results.

1. Sorting Results (`sort`)

You can sort product listings by price in ascending or descending order.

sort=price_asc: Sorts products from lowest to highest price.
sort=price_desc: Sorts products from highest to lowest price.

Example: /products?sort=price_asc

2. Pagination (`pg`)

To retrieve a specific range of results, use the pg parameter. It takes a start-end format. Note that it's 1-indexed.

pg=1-10: Retrieves the first 10 results.
pg=11-20: Retrieves results from the 11th to the 20th item.

Example: /products?pg=5-15

3. Limiting Results (`limit`)

To cap the total number of results returned, use the limit parameter.

limit=5: Returns only the first 5 results.

Example: /products?limit=3

These parameters can be combined to achieve more precise data retrieval, e.g., /products?sort=price_asc&pg=1-10&limit=5 (note that limit is applied after pg is processed, so limit might override the upper bound of pg if it's smaller).

Error Handling

The Byserva API returns clear, JSON-formatted error messages to help you debug and handle issues gracefully in your application.

Standard Error Format:

{
  "error": "string",    // A human-readable error message
  "success": false      // Indicates that the request failed
}

Common HTTP Status Codes:

200 OK: The request was successful, and the response body contains the requested data.

400 Bad Request: The request was malformed or missing required parameters. For example, an invalid path structure or missing fields in a POST request.

{ "error": "Invalid path. Expected /{storeId}/{resource}", "success": false }

{ "error": "Missing required fields: message or email.to_email", "success": false }

404 Not Found: The requested resource (e.g., product, collection, or endpoint) could not be found.

{ "error": "Product not found", "success": false }

{ "error": "Endpoint not found", "success": false }

409 Conflict: Indicates a conflict with the current state of the server. This is typically seen with the /validate endpoint if the client-side cart total does not match the server-side calculated total.
```
{ "error": "Price mismatch. Server: 8000, Client: 7500", "success": false }
```
500 Internal Server Error: A generic error indicating something went wrong on the server's side. This typically points to an unexpected issue within the API itself.
```
{ "error": "An unexpected error occurred.", "success": false }
```

Use Cases & Benefits

The Byserva Public API is engineered to empower developers and businesses with ultimate flexibility in their e-commerce operations.

Headless E-commerce

Separate your frontend presentation layer from your backend commerce logic. This allows for unparalleled design freedom and the ability to use any frontend technology (React, Vue, Angular, Next.js, etc.) to build a truly unique shopping experience.

Custom Storefronts

Go beyond traditional e-commerce templates. Build highly customized online stores, mobile apps, or even IoT commerce experiences that are perfectly tailored to your brand and customer needs.

Shopify Alternative

For merchants who find existing platforms too restrictive or too costly, Byserva offers a lightweight, developer-friendly alternative. Gain full control over your data, performance, and scaling without being locked into a specific ecosystem.

Lightweight & Scalable

Built on Cloudflare Workers, the Byserva API is designed for speed and global scalability. It can handle high traffic volumes efficiently, ensuring a smooth experience for your customers worldwide.

Overview of Byserva API

API Root URL

Obtaining Your Store ID

Steps to Get Your Store ID:

Basic Request Structure

CORS Policy

Detailed API Endpoints

Products API

1. Get All Products

Example Request (List all products, sorted by price ascending, limit 2)

Example Response (200 OK)

2. Get a Single Product by ID

Example Request (Get product 'Pompom')

Example Response (200 OK)

Collections API

1. Get All Collections

Example Request (List all collections)

Example Response (200 OK)

2. Get a Single Collection with Products

Example Request (Get 'XOXO Donuts' collection with products)

Example Response (200 OK)

Validation API

1. Validate Cart Items and Total

Example Request (Validate a cart with demo products)

Example Response (200 OK - Valid Cart)

Example Response (400 Bad Request - Product Missing)

Example Response (409 Conflict - Price Mismatch)

Notify API

1. Send a Notification / Email

Example Request (Send an order confirmation email)

Example Response (200 OK)

Example Response (400 Bad Request - Missing Fields)

General Query Parameters & Filters

1. Sorting Results (sort)

2. Pagination (pg)

3. Limiting Results (limit)

Error Handling

Standard Error Format:

Common HTTP Status Codes:

Use Cases & Benefits

Headless E-commerce

Custom Storefronts

Shopify Alternative

Lightweight & Scalable

1. Sorting Results (`sort`)

2. Pagination (`pg`)

3. Limiting Results (`limit`)