🛍️ BuildMyOnlineStore API

📖 Overview

The BuildMyOnlineStore API enables third-party applications to integrate with merchant storefronts for checkout processing. This API is designed for separating consumer checkout experiences from merchant shopping carts.

Base URL

https://app.buildmyonlinestore.com

Use Cases

• External checkout applications (secure.checkout.best integration)
• Custom payment gateways
• Shopping cart integrations
• Product feed aggregators
• ChatGPT commerce integrations (ACP)

Architecture

• Product Catalog: db.51exports.com (product database only - read-only)
• Payment Processing: secure.checkout.best (handles ALL payments, cart, checkout)
• Storefront Builder: app.buildmyonlinestore.com (this API - CMS/builder only)

🔐 Authentication

All API requests require authentication using GFAVIP SSO tokens.

Token Format

Authorization: Bearer gfavip-session-{token}

How to Obtain Tokens

1. Merchants authenticate via GFAVIP SSO
2. Token is provided in the SSO callback
3. Token must be validated with GET /api/auth/validate
4. Use the token in API requests

{
  "valid": true,
  "user": {
    "id": "7ee04dbe-17f1-45ca-b8b5-a6e34098b074",
    "email": "[email protected]",
    "username": "merchant123",
    "tier": "paid",
    "credits": 150
  }
}

🏪 Storefronts API

Access merchant storefronts and configuration data.

{
  "storefronts": [
    {
      "id": "uuid",
      "store_name": "My Store",
      "catalog_id": "catalog-uuid",
      "product_id": "SKU-123",
      "storefront_type": "multi_product",
      "theme": "modern",
      "color_code": "#667eea",
      "status": "active",
      "checkout_best_store_id": "checkout-uuid",
      "created_at": "2025-11-24T10:00:00Z",
      "updated_at": "2025-11-24T12:00:00Z"
    }
  ]
}

{
  "catalog_id": "abc123-uuid",
  "product_id": "SKU-001",
  "store_name": "My Awesome Store",
  "storefront_type": "ai_single_product",
  "theme": "modern",
  "color_code": "#667eea"
}

{
  "id": "new-storefront-uuid",
  "checkout_best_store_id": "checkout-store-uuid"
}

📦 Product Feed API

OpenAI Agentic Commerce Protocol (ACP) compatible product feeds.

{
  "merchant_id": "merchant-uuid",
  "storefront_id": "storefront-uuid",
  "products": [
    {
      "id": "SKU-123",
      "name": "Premium Wireless Speaker",
      "description": "High-quality bluetooth speaker...",
      "price": 79.99,
      "currency": "USD",
      "image_url": "https://example.com/image.jpg",
      "availability": "in_stock"
    }
  ],
  "checkout_enabled": true
}

{
  "id": "SKU-123",
  "title": "Premium Wireless Speaker",
  "description": "High-quality bluetooth speaker...",
  "price": 79.99,
  "image": "https://example.com/image.jpg",
  "category": "Electronics",
  "in_stock": true
}

💳 Checkout Integration

BuildMyOnlineStore uses secure.checkout.best for ALL checkout processing.

Storefronts automatically include the checkout.best JavaScript widget. No API calls needed from your application.

How It Works

1. When a storefront is created, BuildMyOnlineStore provisions a dedicated checkout.best store
2. Exported static HTML includes the widget script with the store ID
3. The widget handles cart, checkout, and payment processing
4. Order confirmations are sent via webhook (for display purposes only)

Widget Integration (Automatic)

<script src="https://secure.checkout.best/widget.js" 
        data-store="STORE_ID"></script>

<button class="checkout-best-btn" 
        data-sku="PROD-001" 
        data-name="Product Name" 
        data-price="19.99">
    Buy Now
</button>

Webhook Endpoint

{
  "acp_enabled": true,
  "message": "ChatGPT commerce integration available",
  "regions_supported": ["US"]
}

💻 Code Examples

JavaScript/Node.js

// Get merchant's storefronts
async function getMerchantStorefronts(ssoToken) {
  const response = await fetch('https://app.buildmyonlinestore.com/api/storefronts', {
    headers: {
      'Authorization': `Bearer ${ssoToken}`,
      'Content-Type': 'application/json'
    }
  });
  
  return await response.json();
}

// Get product feed
async function getProductFeed(storefrontId) {
  const response = await fetch(
    `https://app.buildmyonlinestore.com/agentic-commerce/feeds/${storefrontId}`
  );
  
  return await response.json();
}

// Initiate checkout
async function initiateCheckout(productId, storefrontId, quantity = 1) {
  const response = await fetch(
    'https://app.buildmyonlinestore.com/agentic-commerce/checkout',
    {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        product_id: productId,
        storefront_id: storefrontId,
        quantity: quantity
      })
    }
  );
  
  const data = await response.json();
  
  if (data.checkout_url) {
    window.location.href = data.checkout_url;
  }
  
  return data;
}

Python

import requests

def get_merchant_storefronts(sso_token):
    """Get all storefronts for authenticated merchant"""
    headers = {
        'Authorization': f'Bearer {sso_token}',
        'Content-Type': 'application/json'
    }
    
    response = requests.get(
        'https://app.buildmyonlinestore.com/api/storefronts',
        headers=headers
    )
    
    return response.json()

def get_product_feed(storefront_id):
    """Get OpenAI ACP-compliant product feed"""
    response = requests.get(
        f'https://app.buildmyonlinestore.com/agentic-commerce/feeds/{storefront_id}'
    )
    
    return response.json()

def initiate_checkout(product_id, storefront_id, quantity=1):
    """Initiate checkout process"""
    data = {
        'product_id': product_id,
        'storefront_id': storefront_id,
        'quantity': quantity
    }
    
    response = requests.post(
        'https://app.buildmyonlinestore.com/agentic-commerce/checkout',
        json=data
    )
    
    return response.json()

cURL

# Get storefronts (authenticated)
curl -X GET "https://app.buildmyonlinestore.com/api/storefronts" \
  -H "Authorization: Bearer gfavip-session-abc123" \
  -H "Content-Type: application/json"

# Get product feed (public)
curl -X GET "https://app.buildmyonlinestore.com/agentic-commerce/feeds/{storefront_id}"

# Initiate checkout
curl -X POST "https://app.buildmyonlinestore.com/agentic-commerce/checkout" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": "SKU-123",
    "storefront_id": "uuid",
    "quantity": 1
  }'

🔒 Internal Service-to-Service API

For authorized GFAVIP mini-apps (e.g., dropshipsitetoday) to provision storefronts on behalf of users.

{
  "success": true,
  "storefront": {
    "id": "new-storefront-uuid",
    "store_name": "My Store",
    "checkout_best_store_id": "checkout-store-uuid",
    "status": "active",
    "created_at": "2025-12-18T10:00:00Z"
  }
}

{
  "success": false,
  "error": "STOREFRONT_LIMIT_REACHED",
  "message": "User has reached maximum storefront limit for their tier",
  "current_count": 1,
  "max_allowed": 1,
  "tier": "free"
}

{
  "success": true,
  "storefronts": [
    {
      "id": "storefront-uuid",
      "store_name": "My Store",
      "storefront_type": "multi_product",
      "status": "active",
      "checkout_best_store_id": "checkout-uuid",
      "created_at": "2025-12-18T10:00:00Z"
    }
  ]
}

🚀 Integration Workflow

1. Merchant Authentication: Merchant logs in via GFAVIP SSO and authorizes your app
2. Get Storefronts: Use merchant's SSO token to fetch their storefronts
3. Display Products: Access product feeds (product data from db.51exports.com)
4. Process Checkout: When customer clicks "Buy", call checkout API
5. Secure Payment: API redirects customer to secure.checkout.best for payment processing
6. Complete Order: secure.checkout.best handles payment and order fulfillment

System Architecture

📊 Response Codes

⚠️ Rate Limits

Currently, there are no enforced rate limits. However, please be respectful:

• Product feeds: Cache for at least 5 minutes
• Storefront data: Cache for at least 15 minutes
• Avoid making more than 100 requests per minute per merchant

🔗 Additional Resources

• Custom Buy Now Buttons Guide - Build custom buttons for Astro, Next.js, and static sites
• GFAVIP SSO Documentation
• 51Exports Product Catalog API (read-only product data)
• Secure Checkout Best Payment API (payment processing)
• OpenAI Agentic Commerce Protocol

💬 Support

For API support and questions:

• Email: [email protected]
• GFAVIP Community Forum
• Report issues on GitHub (if applicable)