---
name: buildmyonlinestore
version: 1.0.0
description: Merchant store, catalog, buy-now, and agentic commerce control hub for BuildMyOnlineStore.
homepage: https://app.buildmyonlinestore.com
metadata: {"bmos":{"category":"commerce","api_base":"https://app.buildmyonlinestore.com"}}
---

# BuildMyOnlineStore Agent Skill

> **URL:** https://app.buildmyonlinestore.com/skill.md
> **Platform:** Merchant store, catalog, buy-now, and agentic commerce control hub
> **Auth:** GFAVIP SSO Bearer Token

BuildMyOnlineStore, also called BMOS, lets merchants manage stores, catalogs, buy-now buttons, marketing feeds, orders, HeadlessDomains domain sync, and agentic commerce setup.

## Authentication

BMOS uses GFAVIP Wallet SSO. AI agents must authenticate headlessly by obtaining a GFAVIP SSO token, then sending it to BMOS as a Bearer token.

Do not use browser redirects for headless access.

### Agent Login Flow

1. Use your PowerLobster API key to obtain an identity token from PowerLobster.

```bash
curl -X POST https://powerlobster.com/api/agent/identity-token \
  -H "Authorization: Bearer YOUR_POWERLOBSTER_API_KEY"
```

2. Exchange the identity token for a GFAVIP SSO token.

```bash
curl -X POST https://wallet.gfavip.com/api/auth/powerlobster \
  -H "Content-Type: application/json" \
  -d '{"token":"YOUR_POWERLOBSTER_IDENTITY_TOKEN"}'
```

3. Use the returned `gfavip-session-...` token with BMOS APIs.

```bash
curl https://app.buildmyonlinestore.com/api/storefronts \
  -H "Authorization: Bearer gfavip-session-YOUR_TOKEN"
```

For the canonical GFAVIP Wallet skill and authentication details, read:

https://wallet.gfavip.com/skill.md

For the broader PowerLobster agent identity flow, read:

https://powerlobster.com/skill.md

## Security Rules

- Never send your PowerLobster API key to BMOS.
- Never send your GFAVIP SSO token to domains other than trusted GFAVIP ecosystem applications.
- BMOS expects `Authorization: Bearer gfavip-session-...`.
- If a BMOS API returns `401`, obtain a fresh GFAVIP SSO token and retry.

## Core BMOS API Endpoints

Base URL:

```text
https://app.buildmyonlinestore.com
```

All protected API examples below require:

```text
Authorization: Bearer gfavip-session-YOUR_TOKEN
```

### Get Agent Context

Use this as the first call after authentication. It returns the GFAVIP user, plan capabilities, team memberships, and stores the account can access.

```bash
curl https://app.buildmyonlinestore.com/api/agent/context \
  -H "Authorization: Bearer gfavip-session-YOUR_TOKEN"
```

### List Stores

```bash
curl https://app.buildmyonlinestore.com/api/storefronts \
  -H "Authorization: Bearer gfavip-session-YOUR_TOKEN"
```

By default this returns stores owned by the authenticated GFAVIP user.

### List Own And Team Stores

Use this when an AI agent may have been added to another merchant's BMOS team.

```bash
curl "https://app.buildmyonlinestore.com/api/storefronts?include_team=true" \
  -H "Authorization: Bearer gfavip-session-YOUR_TOKEN"
```

Team-accessible stores include `merchant_id`, `merchant_email`, `merchant_username`, `access_role`, `access_level`, and `team_membership_id`.

### List Teams This Account Belongs To

```bash
curl https://app.buildmyonlinestore.com/api/team/my-memberships \
  -H "Authorization: Bearer gfavip-session-YOUR_TOKEN"
```

### List Stores For One Team Account

Use the `merchant_id` returned by `/api/team/my-memberships`.

```bash
curl "https://app.buildmyonlinestore.com/api/storefronts?merchant_id=MERCHANT_GFAVIP_USER_ID" \
  -H "Authorization: Bearer gfavip-session-YOUR_TOKEN"
```

### Get Store Details

```bash
curl https://app.buildmyonlinestore.com/api/storefronts/STORE_ID \
  -H "Authorization: Bearer gfavip-session-YOUR_TOKEN"
```

This works for stores owned by the authenticated account and for stores where the account has active team access.

### Create Store

Create a merchant store. If `catalog_id` is omitted, BMOS provisions a private db.51exports.com catalog for the store.

```bash
curl -X POST https://app.buildmyonlinestore.com/api/storefronts \
  -H "Authorization: Bearer gfavip-session-YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "store_name": "Demo Store",
    "storefront_type": "buy_now_buttons",
    "theme": "basic",
    "color_code": "#667eea",
    "use_stripe": false
  }'
```

Free accounts can create one store. Agentic commerce features require a paid/team account.

Important: `storefront_type: "buy_now_buttons"` creates a human checkout / buy-now store. It does not automatically publish the public agentic feed. To publish an agentic feed, the merchant account must have a paid/team plan with machine checkout enabled, and the store must have `ai_agent_selling_enabled: true`.

### Update Store Settings

```bash
curl -X PUT https://app.buildmyonlinestore.com/api/storefronts/STORE_ID \
  -H "Authorization: Bearer gfavip-session-YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "store_name": "Updated Store Name",
    "domain_name": "example.agent",
    "ai_agent_selling_enabled": true,
    "payment_protocols": ["x402"],
    "checkout_protocols": ["bmos-agentic"],
    "refund_policy_url": "https://example.com/refunds",
    "terms_url": "https://example.com/terms"
  }'
```

Common update fields: `store_name`, `theme`, `color_code`, `tax_rate`, `shipping_options`, `use_stripe`, `domain_name`, `logo_url`, `ai_agent_selling_enabled`, `payment_protocols`, `checkout_protocols`, `refund_policy_url`, `terms_url`, `spending_policy_url`, and `order_webhook`.

If `ai_agent_selling_enabled: true` returns `402`, the account is not on a plan that supports machine checkout / agentic commerce yet.

### List Store Products

```bash
curl https://app.buildmyonlinestore.com/api/storefronts/STORE_ID/products \
  -H "Authorization: Bearer gfavip-session-YOUR_TOKEN"
```

### Public Agentic Feed Field Contract

The public BMOS agentic feed is the source of truth for Store Builder and external AI developer agents:

```text
https://app.buildmyonlinestore.com/agentic-commerce/feeds/STORE_ID
```

Important product field mapping:

- Use `id` as the checkout SKU for `.bmos-buy data-product-id`.
- Use `title` as the product display name.
- Use `image_link` as the primary image URL.
- Use `offers.price` and `offers.priceCurrency` for price display.
- Do not assume feed products have `name`, `image`, `images`, or a top-level `price` field.

When integrating BMOS into an existing site, preserve or repair the site's product adapter. Do not remove mock/fallback data or change SKU wiring unless the replacement adapter still maps titles, images, prices, slugs, and descriptions correctly. Before declaring success, verify that collection and product pages do not show blank titles, blank prices, `No Image`, `undefined`, placeholder products, or unavailable BMOS buttons when the feed contains real products.

If `feed_info.agent_domain` or `merchant.agent_domain` is empty, no `.agent` domain is currently bound to that BMOS storefront. Bind a HeadlessDomains `.agent` domain in BMOS Agentic Store settings, then resync.

### List Attached Catalogs

```bash
curl https://app.buildmyonlinestore.com/api/storefronts/STORE_ID/catalogs \
  -H "Authorization: Bearer gfavip-session-YOUR_TOKEN"
```

### Attach Authorized Catalog to Store

The merchant must already be authorized to sell from the db.51exports.com catalog.

```bash
curl -X POST https://app.buildmyonlinestore.com/api/storefronts/STORE_ID/catalogs \
  -H "Authorization: Bearer gfavip-session-YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"catalog_id":"CATALOG_ID"}'
```

### Add Product to a Catalog

Use this when a merchant owns or can edit a db.51exports.com catalog from inside BMOS.

```bash
curl -X POST https://app.buildmyonlinestore.com/api/catalogs/CATALOG_ID/products \
  -H "Authorization: Bearer gfavip-session-YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Custom T-Shirt",
    "description": "Soft cotton shirt",
    "price": 29.00,
    "currency": "USD",
    "quantity": 100,
    "sku": "shirt-001",
    "brand": "Demo Brand",
    "category": "Apparel",
    "main_image": "https://example.com/images/shirt.png"
  }'
```

### Update Catalog Product

The merchant must own or have product-edit rights for the catalog.

```bash
curl -X PUT https://app.buildmyonlinestore.com/api/catalogs/CATALOG_ID/products/PRODUCT_ID \
  -H "Authorization: Bearer gfavip-session-YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Custom T-Shirt",
    "description": "Updated product description",
    "price": 31.00,
    "quantity": 75
  }'
```

### Set Store Product Price

Use this when the merchant can sell a product but does not own the supplier catalog. This changes the store-specific selling price, not the supplier catalog product.

```bash
curl -X PUT https://app.buildmyonlinestore.com/api/storefronts/STORE_ID/pricing/PRODUCT_ID \
  -H "Authorization: Bearer gfavip-session-YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "custom_price": 39.00,
    "currency": "USD",
    "exclude_from_agents": false
  }'
```

### Set Product Landing URL

```bash
curl -X PUT https://app.buildmyonlinestore.com/api/storefronts/STORE_ID/product-urls/PRODUCT_ID \
  -H "Authorization: Bearer gfavip-session-YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "product_url": "https://merchant.example.com/products/shirt-001",
    "variant_urls": {}
  }'
```

### Configure Agentic Payment Rails

Paid/team merchants can configure multiple machine-payment rails on one store.

```bash
curl -X POST https://app.buildmyonlinestore.com/api/storefronts/STORE_ID/agentic-commerce/connect \
  -H "Authorization: Bearer gfavip-session-YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "rails": [
      {
        "rail_type": "base",
        "receive_address": "0xMERCHANT_BASE_ADDRESS",
        "enabled": true,
        "is_primary": true
      },
      {
        "rail_type": "tempo",
        "receive_address": "0xMERCHANT_TEMPO_ADDRESS",
        "enabled": true,
        "is_primary": false
      },
      {
        "rail_type": "solana",
        "receive_address": "MERCHANT_SOLANA_ADDRESS",
        "enabled": false,
        "is_primary": false
      }
    ]
  }'
```

### Sync HeadlessDomains Metadata

After saving a domain or feed settings, call sync so BMOS updates HeadlessDomains records/profile metadata.

```bash
curl -X POST https://app.buildmyonlinestore.com/api/storefronts/STORE_ID/sync \
  -H "Authorization: Bearer gfavip-session-YOUR_TOKEN"
```

### Get Agentic Commerce Feed

This public feed is used by shopping agents.

```bash
curl https://app.buildmyonlinestore.com/agentic-commerce/feeds/STORE_ID
```

If the feed returns `{"error":"AI agent selling is disabled for this storefront"}`, the store exists but is not published for agentic commerce. The merchant must enable agentic selling on a paid/team account and configure agentic payment rails first.

### Create Agentic Checkout Session

Agents can request checkout for a product/offer through BMOS. BMOS routes machine payments through machine.checkout.best.

```bash
curl -X POST https://app.buildmyonlinestore.com/agentic-commerce/checkout \
  -H "Content-Type: application/json" \
  -d '{
    "storefront_id": "STORE_ID",
    "product_id": "SKU_OR_OFFER_ID",
    "quantity": 1,
    "rail_type": "base",
    "buyer_agent": "your-agent-name"
  }'
```

Supported agentic rails may include `base`, `tempo`, `solana`, and `coinbase`, depending on what the merchant has enabled.

## HeadlessDomains Integration

When a merchant binds a `.agent` domain in BMOS, BMOS syncs agentic commerce metadata to HeadlessDomains and publishes a TXT record like:

```text
TXT @ bmos:https://app.buildmyonlinestore.com/agentic-commerce/feeds/STORE_ID
```

Agents may discover a merchant's BMOS feed from HeadlessDomains DNS/profile data, then fetch the feed directly.

## Agent Behavior Guidelines

- Prefer read-only inspection unless the human explicitly asks you to make changes.
- When showing store, catalog, or order results to a human, include the relevant BMOS URL when available.
- If a merchant has multiple payment rails enabled, use the rail requested by the human or the buyer agent. If no rail is requested, use the store primary rail.
- Do not assume Stripe/human checkout is connected just because agentic checkout is connected; BMOS treats human and agentic rails separately.