Build a Customer Portal with the BSimple API

Build a Customer Portal with the BSimple API

A customer portal can use the BSimple API to show selected customer, inventory and invoice information without exposing the full BSimple application. The safest design keeps the API key on your server, gives the integration only the scopes it needs, and treats BSimple as the source of truth for the data it owns.

Start with the customer journey

Decide which actions the portal must support before selecting scopes:

• Show products and current availability.
• Show a customer's invoices and account information.
• Capture a lead or update customer details.
• Submit an order as a draft invoice for internal review.
• Show location or reorder information to an internal user rather than a customer.

A customer-facing portal usually needs fewer permissions than an internal operations dashboard. Do not grant inventory:write, leads:write or invoices:write simply because the integration may need them later.

Keep the API key server-side

The browser should call your portal application, not BSimple directly. Your server then calls BSimple with X-API-Key. This prevents the key from being embedded in browser JavaScript, page source, mobile bundles or public network requests.

Use a separate key for each environment and integration. Name keys so an administrator can identify the owner and revoke one connection without taking down unrelated systems.

Suggested scope sets

These are starting points, not a substitute for testing the exact endpoint requirements in the API reference.

Design around draft workflow

The current invoice write endpoint creates a draft/pre-draft invoice. It does not approve, send or pay the invoice. That is useful when the portal captures an order but staff still need to review pricing, availability, delivery or tax treatment in BSimple.

Read create a draft invoice before treating an online order as complete. Your portal should show a clear pending state until the BSimple-side workflow has accepted the draft.

Protect customer data

Return only the fields the customer needs. Apply your own portal authorisation before passing a BSimple identifier to an endpoint. Do not trust a customer-supplied customer_id; map the authenticated portal account to the permitted BSimple customer on your server.

Keep API keys, full responses and customer data out of browser analytics, application logs and error messages. Define retention and deletion rules for any local copy of BSimple data.

Handle synchronisation gaps

The BSimple API currently does not provide webhooks. A portal that needs fresh data should use bounded reads and reconciliation rather than claiming that every change arrives instantly. The polling and reconciliation guide covers the current pattern.

Build in stages

1. Start with one read-only use case.
2. Verify scope failures and missing records.
3. Add pagination and safe caching.
4. Add draft submission only after the read path is reliable.
5. Add monitoring, key rotation and a reconciliation job.

For the first request, follow Getting started. For native and custom connection options, see BSimple Integrations.