Appearance
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 theAuthorizationheader, sendX-BMA-Host-Key: mph_…instead. - Limits: 120 calls a minute per host, then
429withretry_afterin seconds. Wrong keys count against the calling address: after 30 in 5 minutes that address gets429for every call, even with the right key, until the 5 minutes pass. Fix a wrong key before retrying.
- 1Create the API key (or replace it). It is shown once, so copy it to your server straight away.
- 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
| Call | What it does |
|---|---|
GET /me | your 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>/entitlements | what that customer has (see below) |
GET /customers/<external_org_id>/subscriptions | its subscriptions in your marketplaces |
GET /customers/<external_org_id>/orders | its orders in your marketplaces |
GET /entitlements, /subscriptions, /orders [?updated_since=&after=&limit=] | the same for all your customers |
GET /customers/<external_org_id>/menu | the vendor screens that customer's products add to your platform's navigation (see Vendor screens in your menus) |
POST /customers/<external_org_id>/launch | a signed address of one of those screens for one of your users |
external_org_idis your own id for the organization: the same value you send asorg_idin 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. Passafter=<next_after>for the next page until it isnull.limitis 1 to 200 (default 100). server_timeis BMA's clock when the list was read, in ISO 8601 with its offset (for example2026-11-15T09:30:00-06:00). Keep the first page's value and send it asupdated_sinceon your next sync: nothing that changed while you were reading is missed, and your clock doesn't have to agree with BMA's.updated_sincetakesYYYY-MM-DD,YYYY-MM-DD HH:MM[:SS], or ISO 8601 withZor 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 theupdated_atvalues BMA returns. A value BMA can't read is ignored (you get everything), not refused.
Entitlement rows
| Field | Meaning |
|---|---|
external_org_id | your customer |
marketplace, product (slug), product_name, product_type, plan | what they have |
subscription_id | BMA's id for it |
status | onboarding, pending, trialing, active, past_due, suspended, cancelled or ended |
entitlement | BMA's switch: on, off, provisioning, suspended or failed |
active | the 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_end | when the current period ends, and whether it then stops |
updated_at | last 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.
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 (
categoryis the product's first category in that marketplace, orOther).parentis another item'skey(nest it under that item).iconis anmdi-name or null. Cache it, and read it again when the customer's entitlements change (webhooks, orupdated_since) and every hour or so, since a vendor's next approved version can change the screens.When a user clicks an entry, ask for its address from your server:
POST /customers/<external_org_id>/launchwith{ "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.idis your own id (letters, digits and. _ : @ -, at most 64); the vendor sees it ashost:<your host id>:<id>.Open the answer's
urlstraight away: it's signed and expires in about two minutes. With"open": "iframe", put it in a frame withsandbox="allow-scripts allow-forms allow-same-origin allow-popups allow-popups-to-escape-sandbox allow-downloads allow-modals"andreferrerpolicy="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 code | Meaning |
|---|---|
not_found | not your customer, or the subscription isn't in your marketplaces |
nav_item_not_found | the screen isn't in the product's live version any more: read the menu again |
not_active | the subscription ended or isn't set up yet |
invalid_input | subscription_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>, wherev1 = 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))| Event | When |
|---|---|
entitlement.granted | a 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.suspended | a product was suspended, for example unpaid |
entitlement.revoked | a customer no longer has the product (cancelled or ended) |
customer.created | a customer organization was made, through PUT /customers/… (via: "api") or its first sign-in (via: "sign_in") |
| also | listing.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:
| Status | When |
|---|---|
401 | no key, a wrong key, or the host isn't active |
404 | not found, including another host's customer, or a path that doesn't exist |
409 | no_marketplace: BMA hasn't set up a marketplace for your host yet |
422 | bad input; data.field names the field (customer id, name over 128 characters, email, meta not an object or over 4 KB) |
429 | too many calls; wait retry_after seconds (also in the Retry-After header) |
500 | unavailable: 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.