Skip to content
ReferenceForDeveloperHost owner⏱ About 20 min
Before you start:
  • A host API key (an owner creates it in the host portal under API & webhooks)
  • Your servers able to make HTTPS calls

Host API and webhooks ​

For a hostHost A company that shows a BMA marketplace inside its own software, for its own customers. A host can approve listings, vet vendors, sell ads and read reports. that runs a BMA marketplace inside its own product. Your servers use this API to:

  • keep BMA's list of your customer organizations in step with yours;
  • read what each customer has, so you can switch your side on or off;
  • get webhooksWebhook A message BMA sends to your server when something happens, such as a customer getting access to a product. Each one is signed so you can check it came from BMA. when a customer gains or loses a product.

Buying still happens in the embedded marketplace. The full contract is in the OpenAPI file, which you can also import into Postman or Insomnia.

Authentication ​

  • The key: an owner of your host creates it in the host portal (API & webhooks), or BMA staff do. It starts with mph_ and is shown once; BMA keeps only a hash. Making a new key stops the old one at once.
  • Every call: Authorization: Bearer mph_… over HTTPS, from your servers only. Never put the key in a browser. If a proxy on your side drops the Authorization header, send X-BMA-Host-Key: mph_… instead.
  • Limits: 120 calls a minute per host, then 429 with retry_after in seconds. Wrong keys count against the calling address: after 30 in 5 minutes that address gets 429 for every call, even with the right key, until the 5 minutes pass. Fix a wrong key before retrying.
  1. 1Create the API key (or replace it). It is shown once, so copy it to your server straight away.
  2. 2Add a webhook endpoint: its HTTPS address and the events you want.

Base URL: https://bma.botmodepro.com/mp/v1/host

Every answer looks like {"success": true, "data": {"api_version": "2026-11-13", "data": …}}.

Endpoints ​

CallWhat it does
GET /meyour host and its marketplaces (code, name, status, currency)
GET /catalog?marketplace=<code>what a marketplace sells, the same cards as the storefront (default: your first active marketplace)
PUT /customers/<external_org_id>create or update one of your customer organizations. Body: name (required the first time), email, meta (any JSON object up to 4 KB, kept for you). Returns {customer, created}.
GET /customers[?updated_since=&after=&limit=]your customers, oldest first
GET /customers/<external_org_id>one customer
GET /customers/<external_org_id>/entitlementswhat that customer has (see below)
GET /customers/<external_org_id>/subscriptionsits subscriptions in your marketplaces
GET /customers/<external_org_id>/ordersits orders in your marketplaces
GET /entitlements, /subscriptions, /orders [?updated_since=&after=&limit=]the same for all your customers
GET /customers/<external_org_id>/menuthe vendor screens that customer's products add to your platform's navigation (see Vendor screens in your menus)
POST /customers/<external_org_id>/launcha signed address of one of those screens for one of your users
  • external_org_id is your own id for the organization: the same value you send as org_id in the embed sign-in token. Letters, digits and . _ : -, at most 64 characters. The API and the sign-in reach the same organization, whichever comes first.
  • Paging: lists return {data: [...], next_after, server_time}, oldest first. Pass after=<next_after> for the next page until it is null. limit is 1 to 200 (default 100).
  • server_time is BMA's clock when the list was read, in ISO 8601 with its offset (for example 2026-11-15T09:30:00-06:00). Keep the first page's value and send it as updated_since on your next sync: nothing that changed while you were reading is missed, and your clock doesn't have to agree with BMA's.
  • updated_since takes YYYY-MM-DD, YYYY-MM-DD HH:MM[:SS], or ISO 8601 with Z or an offset (2026-11-15T15:30:00Z), which BMA converts to its own time zone. Without a zone it is read in BMA's time zone, like the updated_at values BMA returns. A value BMA can't read is ignored (you get everything), not refused.

Entitlement rows ​

FieldMeaning
external_org_idyour customer
marketplace, product (slug), product_name, product_type, planwhat they have
subscription_idBMA's id for it
statusonboarding, pending, trialing, active, past_due, suspended, cancelled or ended
entitlementBMA's switch: on, off, provisioning, suspended or failed
activethe one to act on: the customer can use the product now (trialing, active or past due, not suspended or failed, and for vendor-hosted products also set up)
period_end, cancel_at_period_endwhen the current period ends, and whether it then stops
updated_atlast change (UTC)

Vendor screens in your menus ​

Vendors can describe their product's screens (nav_items). When one of your customers has the product (active and set up), show those screens in your own platform's menu, and open them inside your platform (a frame) or in a new tab.

  1. Read the menu for the signed-in customer: GET /customers/<external_org_id>/menu:

    json
    [{ "marketplace": "amx-mp", "subscription_id": 42, "vendor_name": "Northwind Software", "category": "Sales",
       "product_name": "Northwind Desk",
       "items": [{ "key": "dashboard", "title": "Dashboard", "icon": "mdi-view-dashboard", "parent": null, "open": "iframe" }] }]

    Group them as vendor › category › product › screens, as BMA does (category is the product's first category in that marketplace, or Other). parent is another item's key (nest it under that item). icon is an mdi- name or null. Cache it, and read it again when the customer's entitlements change (webhooks, or updated_since) and every hour or so, since a vendor's next approved version can change the screens.

  2. When a user clicks an entry, ask for its address from your server: POST /customers/<external_org_id>/launch with { "subscription_id": 42, "item": "dashboard", "user": { "id": "u-77", "name": "Sam Rivera", "email": "[email protected]", "admin": false } }. You vouch for your user, as with the embed sign-in. user.id is your own id (letters, digits and . _ : @ -, at most 64); the vendor sees it as host:<your host id>:<id>.

  3. Open the answer's url straight away: it's signed and expires in about two minutes. With "open": "iframe", put it in a frame with sandbox="allow-scripts allow-forms allow-same-origin allow-popups allow-popups-to-escape-sandbox allow-downloads allow-modals" and referrerpolicy="no-referrer", and offer Open in new tab (ask again for a fresh address). With "tab", open a new tab.

For the frame to work, the vendor's site must allow your platform's address in its frame-ancestors. Tell vendors your address; their guide is Put your product in the customer's BMA menu.

Error codeMeaning
not_foundnot your customer, or the subscription isn't in your marketplaces
nav_item_not_foundthe screen isn't in the product's live version any more: read the menu again
not_activethe subscription ended or isn't set up yet
invalid_inputsubscription_id, item or user.id missing or malformed

Examples ​

bash
# Create or update a customer
curl -s -X PUT https://bma.botmodepro.com/mp/v1/host/customers/dealer-1042 \
  -H "Authorization: Bearer $BMA_HOST_KEY" -H "Content-Type: application/json" \
  -d '{"name":"Northwind Motors","email":"[email protected]"}'

# What does it have?
curl -s https://bma.botmodepro.com/mp/v1/host/customers/dealer-1042/entitlements \
  -H "Authorization: Bearer $BMA_HOST_KEY"
js
const BASE = 'https://bma.botmodepro.com/mp/v1/host'
const headers = { Authorization: `Bearer ${process.env.BMA_HOST_KEY}`, 'Content-Type': 'application/json' }

export async function syncCustomer(dealer) {
  const r = await fetch(`${BASE}/customers/${encodeURIComponent(dealer.id)}`, {
    method: 'PUT', headers, body: JSON.stringify({ name: dealer.name, email: dealer.email }),
  })
  if (!r.ok) throw new Error(`BMA ${r.status}: ${(await r.json()).message}`)
  return (await r.json()).data.data // { customer, created }
}

export async function activeProducts(dealerId) {
  const r = await fetch(`${BASE}/customers/${encodeURIComponent(dealerId)}/entitlements`, { headers })
  const rows = (await r.json()).data.data.data
  return rows.filter((e) => e.active).map((e) => e.product)
}
php
function bma_host(string $method, string $path, ?array $body = null): array {
    $ch = curl_init('https://bma.botmodepro.com/mp/v1/host' . $path);
    curl_setopt_array($ch, [
        CURLOPT_CUSTOMREQUEST => $method, CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('BMA_HOST_KEY'), 'Content-Type: application/json'],
        CURLOPT_POSTFIELDS => $body === null ? null : json_encode($body),
    ]);
    $res = json_decode((string) curl_exec($ch), true);
    $status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    if ($status >= 400) throw new RuntimeException("BMA $status: " . ($res['message'] ?? ''));
    return $res['data']['data'];
}

bma_host('PUT', '/customers/dealer-1042', ['name' => 'Northwind Motors', 'email' => '[email protected]']);
$active = array_column(array_filter(bma_host('GET', '/customers/dealer-1042/entitlements')['data'],
    fn ($e) => $e['active']), 'product');
python
import os, requests

BASE = "https://bma.botmodepro.com/mp/v1/host"
H = {"Authorization": f"Bearer {os.environ['BMA_HOST_KEY']}"}

def sync_customer(dealer_id, name, email=None):
    body = {"name": name, **({"email": email} if email else {})}
    r = requests.put(f"{BASE}/customers/{dealer_id}", json=body, headers=H, timeout=15)
    r.raise_for_status()
    return r.json()["data"]["data"]

def active_products(dealer_id):
    r = requests.get(f"{BASE}/customers/{dealer_id}/entitlements", headers=H, timeout=15)
    r.raise_for_status()
    return [e["product"] for e in r.json()["data"]["data"]["data"] if e["active"]]

To read every change since your last sync, page through GET /entitlements?updated_since=<server_time of your last sync> until next_after is null, then keep this sync's first server_time for next time.

Webhooks ​

An owner adds endpoints in the host portal (API & webhooks) and picks the events. The signing secret starts with whsec_ and is shown once. Each delivery is a POST with {id, type, api_version, created_at, data} and these headers:

  • BMA-Event, BMA-Delivery, BMA-Webhook-Id;
  • BMA-Signature: t=<unix>,v1=<hex>, where v1 = HMAC-SHA256(secret, "<t>.<raw body>").

Check the signature, reject a t older than 5 minutes, and answer 2xx quickly (do the work afterwards). The Webhooks page has more detail and a signature checker. Failed deliveries are retried up to 8 times with backoff. An endpoint is switched off after 25 failures in a row; an owner can switch it back on in the portal.

js
import crypto from 'node:crypto'

// rawBody: the exact bytes received, before any JSON parsing.
export function bmaWebhookOk(rawBody, header, secret, now = Math.floor(Date.now() / 1000)) {
  const m = /^t=(\d+),v1=([0-9a-f]{64})$/.exec(header || '')
  if (!m || Math.abs(now - Number(m[1])) > 300) return false
  const want = crypto.createHmac('sha256', secret).update(`${m[1]}.${rawBody}`).digest('hex')
  return crypto.timingSafeEqual(Buffer.from(want), Buffer.from(m[2]))
}
php
function bma_webhook_ok(string $rawBody, string $header, string $secret): bool {
    if (!preg_match('/^t=(\d+),v1=([0-9a-f]{64})$/', $header, $m) || abs(time() - (int) $m[1]) > 300) {
        return false;
    }
    return hash_equals(hash_hmac('sha256', $m[1] . '.' . $rawBody, $secret), $m[2]);
}
// $ok = bma_webhook_ok(file_get_contents('php://input'), $_SERVER['HTTP_BMA_SIGNATURE'] ?? '', getenv('BMA_WEBHOOK_SECRET'));
python
import hashlib, hmac, re, time

def bma_webhook_ok(raw_body: bytes, header: str, secret: str) -> bool:
    m = re.fullmatch(r"t=(\d+),v1=([0-9a-f]{64})", header or "")
    if not m or abs(time.time() - int(m.group(1))) > 300:
        return False
    want = hmac.new(secret.encode(), m.group(1).encode() + b"." + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(want, m.group(2))
EventWhen
entitlement.granteda customer can now use a product: a trial or paid start, a no-charge or invoiced order that starts at once, or a reactivation after suspension
entitlement.suspendeda product was suspended, for example unpaid
entitlement.revokeda customer no longer has the product (cancelled or ended)
customer.createda customer organization was made, through PUT /customers/… (via: "api") or its first sign-in (via: "sign_in")
alsolisting.requested, listing.status_changed, order.status_changed, subscription.status_changed, invoice.*, payment.*, statement.ready, payout.sent, … (the portal lists them all)

Entitlement events carry external_org_id, subscription_id, product, product_name, plan, status, from and period_end.

Treat events as hints

Events can arrive late or twice: dedupe on id. The entitlements endpoint is the truth, so re-read it on a schedule (for example nightly, with updated_since).

Errors ​

{"success": false, "message": "...", "data": {"code": "...", ...}} with:

StatusWhen
401no key, a wrong key, or the host isn't active
404not found, including another host's customer, or a path that doesn't exist
409no_marketplace: BMA hasn't set up a marketplace for your host yet
422bad input; data.field names the field (customer id, name over 128 characters, email, meta not an object or over 4 KB)
429too many calls; wait retry_after seconds (also in the Retry-After header)
500unavailable: something failed on BMA's side; try again later

Keys and secrets ​

  • Keep the API key and webhook secrets in your server's secret store, never in code or a browser.
  • To rotate the API key, an owner clicks New API key in the portal. The old key stops at once, so deploy the new one straight away.
  • To rotate a webhook secret, use New secret on the endpoint and update your server.