White-Label Headless Clinic API (V2)

This guide is for engineering partners who connect a white-label storefront or EHR to BioTide with server-to-server (S2S) calls. There is no Swagger UI — this page is the contract.

Your headless API buyer (a clinic node in a Sales Org hierarchy) can:

Pull a priced catalog at their account wholesale cost
Inject paid orders (shipping + routed payment included)
Poll status and tracking

Portal setup (create API buyers, master wallet funding, vaulted cards, payment preference) is done in the wholesale dashboard under My Network → Team hierarchy. See the Sales Organization Guide.

Create an API buyer (credentials)

A Sales Org manager provisions the headless clinic from the wholesale portal. The clinic does not get a normal dashboard login — only API credentials for Basic Auth.

Steps

Sign in at wholesale.biotideusa.com as a Sales Org (or manager who can manage the team).
Open My Network → Team hierarchy (or use Create API Buyer from the Dashboard).
Click Create API Buyer.
Enter a Username (required). Optionally add Company name and Email.
Read the fee notice ($35 shipping on injected orders, plus card processing fees when routing to a vaulted card), then submit.
On success, BioTide shows Username and an Application Password.

Save credentials immediately — they never display again

One-time credentials

The Application Password is shown only once on the success screen after create.

Copy it with the dialog’s copy control (or select and copy manually).
Store Username + Application Password in your secrets manager / password vault before you close the dialog.
BioTide will never show that application password again in the portal UI.

If you lose it, you cannot look it up later. Your WordPress/BioTide admin must issue a new application password for that user (or you create a new API buyer). Treat a lost password as compromised and rotate.

Use those values as API_BUYER_USERNAME and APPLICATION_PASSWORD in every curl example below.

After create, configure payment for that buyer under Team hierarchy → Billing Settings (master wallet vs vaulted card), and keep the Sales Org master wallet funded as needed.

Base URL

text

https://api.biotideusa.com/wp-json/biotide/v1/headless

Method	Path	Purpose
`GET`	`/catalog`	Priced catalog for the authenticated API buyer
`POST`	`/orders`	Create and pay an order
`GET`	`/orders/{id}`	Order status + tracking

Replace placeholders in every example:

Placeholder	Meaning
`API_BUYER_USERNAME`	WordPress username from Create API Buyer
`APPLICATION_PASSWORD`	One-time application password shown at create time
`45678`	BioTide order id returned as `biotide_id`

Authentication

All headless routes use HTTP Basic Auth (WordPress Application Password).

bash

# curl -u sends Authorization: Basic …
curl -u "API_BUYER_USERNAME:APPLICATION_PASSWORD" ...

Equivalent header form:

http

Authorization: Basic base64(API_BUYER_USERNAME:APPLICATION_PASSWORD)
Content-Type: application/json
Accept: application/json

Credentials

Treat the application password like an API secret. BioTide shows it once when the Sales Org creates the API buyer. Store it in your secrets manager; rotate in WordPress if it is exposed.

Order reads (GET /orders/{id}) are limited to orders that belong to the authenticated API buyer.

Fees on injected orders

Applied automatically by BioTide on POST /orders (you do not send fee lines):

Fee	Amount	When
Flat shipping	$35.00	Every injected order
Credit card surcharge	11% of (product subtotal + $35 shipping)	Only when that buyer’s payment preference is vaulted card

Wallet-paid orders do not get the 11% surcharge. Payment preference is set by the Sales Org in the portal (Billing Settings per buyer), not in the order payload.

1. Get catalog

Returns SKUs with hierarchy-verified wholesale prices for the authenticated API buyer.

Always use these prices on your side. Order injection ignores any client-supplied unit price and re-prices from this matrix (anti-spoofing).

Request

bash

curl -X GET "https://api.biotideusa.com/wp-json/biotide/v1/headless/catalog" \
  -u "API_BUYER_USERNAME:APPLICATION_PASSWORD" \
  -H "Accept: application/json"

Body: none.

Success response (`200`)

json

{
  "status": "success",
  "items": [
    {
      "product_id": 123,
      "sku": "BPC-157-5MG",
      "name": "BPC-157 5mg",
      "category": "Peptides",
      "your_wholesale_cost": 42.5,
      "shipping_window": "2-4 business days",
      "image_url": "https://example.com/image.jpg"
    }
  ]
}

Field	Description
`product_id`	WooCommerce product id
`sku`	Use this in `line_items` when creating orders
`your_wholesale_cost`	Unit price for this API buyer (USD)
`shipping_window`	Fulfillment guidance string (informational)
`image_url`	Product image URL when available

Errors

HTTP	Meaning
`401`	Missing or invalid Basic Auth
`500`	Catalog engine unavailable

2. Create order

Creates a WooCommerce order for the authenticated clinic, applies $35 shipping (and 11% CC fee when preference is vaulted card), charges the Sales Org master wallet or vaulted card, then marks the order processing on success.

If payment fails, BioTide returns 402 and does not keep the order.

Request

bash

curl -X POST "https://api.biotideusa.com/wp-json/biotide/v1/headless/orders" \
  -u "API_BUYER_USERNAME:APPLICATION_PASSWORD" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "external_order_id": "PARTNER-9001",
    "line_items": [
      { "sku": "BPC-157-5MG", "qty": 2 },
      { "sku": "TB-500-5MG", "qty": 1 }
    ],
    "shipping_address": {
      "first_name": "Alex",
      "last_name": "Rivera",
      "company": "Example Clinic",
      "address_1": "123 Main St",
      "address_2": "Suite 100",
      "city": "Boise",
      "state": "ID",
      "postcode": "83702",
      "country": "US",
      "phone": "2085550100",
      "email": "ops@example.com"
    }
  }'

Request body fields

json

{
  "external_order_id": "PARTNER-9001",
  "line_items": [
    { "sku": "BPC-157-5MG", "qty": 2 }
  ],
  "shipping_address": {
    "first_name": "Alex",
    "last_name": "Rivera",
    "company": "Example Clinic",
    "address_1": "123 Main St",
    "address_2": "Suite 100",
    "city": "Boise",
    "state": "ID",
    "postcode": "83702",
    "country": "US",
    "phone": "2085550100",
    "email": "ops@example.com"
  }
}

Field	Required	Notes
`line_items`	Yes	Non-empty array
`line_items[].sku`	Yes	Must appear in `GET /catalog` for this buyer
`line_items[].qty`	Yes	Positive integer
`shipping_address`	Yes	WooCommerce-style address object
`shipping_address.first_name`	Recommended	Ship-to contact
`shipping_address.last_name`	Recommended	Ship-to contact
`shipping_address.address_1`	Recommended	Street line 1
`shipping_address.city`	Recommended
`shipping_address.state`	Recommended	2-letter US state when `country` is `US`
`shipping_address.postcode`	Recommended
`shipping_address.country`	Recommended	ISO country code (e.g. `US`)
`shipping_address.company`	No
`shipping_address.address_2`	No
`shipping_address.phone`	No
`shipping_address.email`	No
`external_order_id`	No	Your id; stored for reconciliation and returned later

Do not send unit prices, shipping amounts, or payment tokens in this body — BioTide calculates pricing and routes payment from the buyer’s configured preference.

Success response (`200`)

json

{
  "success": true,
  "biotide_id": 45678,
  "external_id": "PARTNER-9001",
  "order_subtotal": 85.0,
  "shipping": 35.0,
  "fees": 0,
  "order_total": 120.0,
  "status": "Paid / Processing",
  "message": "Order captured and pushed to fulfillment. Headless Payment captured via Sales Org Pre-Funded Wallet. Remaining Balance: $1880.00"
}

Field	Description
`biotide_id`	WooCommerce order id — use this for `GET /orders/{id}`
`external_id`	Echo of `external_order_id` (may be empty)
`order_subtotal`	Sum of line items at verified wholesale cost
`shipping`	Flat shipping (`35`)
`fees`	CC surcharge when preference is vaulted card; otherwise `0`
`order_total`	Final charged total
`status`	Human-readable success status
`message`	Includes payment route notes

Error responses

HTTP	When	Notes
`400`	Missing `line_items` / `shipping_address`, or SKU not allowed	Message names the invalid SKU when applicable
`401`	Bad or missing Basic Auth
`402`	Payment failed	Insufficient wallet, card decline, missing vault, etc. Order is deleted

Example payment failure:

json

{
  "code": "payment_failed",
  "message": "Order rejected. Billing error: Insufficient Master Wallet funds. Order Total: $120.00. Wallet Balance: $10.00.",
  "data": { "status": 402 }
}

3. Get order status & tracking

Returns status and shipment tracking for an order owned by the authenticated API buyer.

{id} is the BioTide / WooCommerce order id from create (biotide_id).

Request

bash

curl -X GET "https://api.biotideusa.com/wp-json/biotide/v1/headless/orders/45678" \
  -u "API_BUYER_USERNAME:APPLICATION_PASSWORD" \
  -H "Accept: application/json"

Body: none.

Success response (`200`)

json

{
  "success": true,
  "biotide_id": 45678,
  "external_id": "PARTNER-9001",
  "status": "processing",
  "date_created": "2026-07-23 18:04:11",
  "tracking": {
    "provider": "UPS",
    "number": "1Z999AA10123456784",
    "link": "https://www.ups.com/track?tracknum=1Z999AA10123456784"
  }
}

Field	Description
`status`	WooCommerce status slug (e.g. `processing`, `completed`)
`date_created`	Order created timestamp (`Y-m-d H:i:s`) or `null`
`tracking.provider`	Carrier name when available; else `""`
`tracking.number`	Tracking number when available; else `""`
`tracking.link`	Carrier tracking URL when available; else `""`

Empty tracking strings usually mean the order is not shipped yet.

Errors

HTTP	Meaning
`401`	Missing or invalid Basic Auth
`403`	Order exists but belongs to a different customer
`404`	Order id not found

How payment is chosen

Configured by the Sales Org in the portal (Team hierarchy → Billing Settings for that API buyer). Your POST /orders call does not pick the method.

Preference	What happens on `POST /orders`
`wallet` (default)	Debit the Sales Org master wallet for `order_total`
`vaulted_card`	Charge the org’s vaulted card; add 11% fee on (subtotal + shipping)

Wallet funding and card vaulting are portal / BioTide operations — not part of this headless clinic API.

Suggested integration flow

mermaid

sequenceDiagram
  participant Partner as Partner backend
  participant BT as BioTide headless API
  participant AuthNet as Authorize.Net

  Partner->>BT: GET /catalog (Basic Auth)
  BT-->>Partner: SKUs + wholesale costs
  Partner->>BT: POST /orders (items + ship-to)
  alt preference wallet
    BT->>BT: Debit Sales Org master wallet
  else preference vaulted_card
    BT->>AuthNet: CIM charge
  end
  BT-->>Partner: biotide_id + totals
  Partner->>BT: GET /orders/{biotide_id}
  BT-->>Partner: status + tracking

Sales Org creates an API buyer and stores username + application password.
Sales Org funds the master wallet and/or vaults a card; sets payment preference.
Your backend: GET /catalog → POST /orders → store biotide_id.
Poll GET /orders/{biotide_id} for fulfillment and tracking.

Quick copy-paste checklist

bash

# 1) Catalog
curl -X GET "https://api.biotideusa.com/wp-json/biotide/v1/headless/catalog" \
  -u "API_BUYER_USERNAME:APPLICATION_PASSWORD" \
  -H "Accept: application/json"

# 2) Create order
curl -X POST "https://api.biotideusa.com/wp-json/biotide/v1/headless/orders" \
  -u "API_BUYER_USERNAME:APPLICATION_PASSWORD" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "external_order_id": "PARTNER-9001",
    "line_items": [{ "sku": "BPC-157-5MG", "qty": 2 }],
    "shipping_address": {
      "first_name": "Alex",
      "last_name": "Rivera",
      "address_1": "123 Main St",
      "city": "Boise",
      "state": "ID",
      "postcode": "83702",
      "country": "US",
      "phone": "2085550100",
      "email": "ops@example.com"
    }
  }'

# 3) Status / tracking (use biotide_id from step 2)
curl -X GET "https://api.biotideusa.com/wp-json/biotide/v1/headless/orders/45678" \
  -u "API_BUYER_USERNAME:APPLICATION_PASSWORD" \
  -H "Accept: application/json"

Support

Portal how-to: Sales Organization Guide
Billing / wallet funding: info@biotideusa.com
Live help center: docs.biotideusa.com

White-Label Headless Clinic API (V2) ​

Create an API buyer (credentials) ​

Steps ​

Save credentials immediately — they never display again ​

Base URL ​

Authentication ​

Fees on injected orders ​

1. Get catalog ​

Request ​

Success response (200) ​

Errors ​

2. Create order ​

Request ​

Request body fields ​

Success response (200) ​

Error responses ​

3. Get order status & tracking ​

Request ​

Success response (200) ​

Errors ​

How payment is chosen ​

Suggested integration flow ​

Quick copy-paste checklist ​

Support ​

White-Label Headless Clinic API (V2)

Create an API buyer (credentials)

Steps

Save credentials immediately — they never display again

Base URL

Authentication

Fees on injected orders

1. Get catalog

Request

Success response (`200`)

Errors

2. Create order

Request

Request body fields

Success response (`200`)

Error responses

3. Get order status & tracking

Request

Success response (`200`)

Errors

How payment is chosen

Suggested integration flow

Quick copy-paste checklist

Support