Get started

API docs

Black Beach POS API

The Black Beach POS API gives outside systems access to a shop's products, inventory (including lot numbers and expiry), customers, orders and purchase orders. Channel managers, marketplaces, email marketing tools and accounting tools can all read from Black Beach POS and write back to it. Changes are pushed to you as signed webhooks.

Customer ID documents, staff notes and staff accounts are never exposed through the API (see Permissions).

Base URLs

Environment Base URL Key prefix
Live https://app.blackbeachpos.com/api/v1 ir_live_
Sandbox https://sandbox.blackbeachpos.com/api/v1 ir_test_

Each server accepts only its own keys. A live key sent to the sandbox, or a sandbox key sent to live, gets 401 WRONG_ENVIRONMENT. See Sandbox for a test shop to build against.

Getting a key

API keys belong to one shop, and only the shop owner can create them. The owner goes to Settings → Developers → API keys → New key, names the key after the system that will use it, and sets what the key may do:

  • Permissions: None, Read or Write for each resource.
  • Locations: limit the key to some stores, or allow all of them.
  • IP allowlist: optional.
  • Expiry date: optional.

The full key is shown once, when it's created. Black Beach POS stores only a hash of it.

If you're a partner integrating on a shop's behalf, the owner creates the key and hands it to you. Ask for the narrowest permissions your integration needs.

Plans and rate limits

Plan API access Per minute Per day
Getting Started No (402 API_NOT_IN_PLAN) – –
Established Yes 60 10,000
Enterprise Yes 600 (fair-use ceiling) No cap
  • Shared across keys. Limits are per shop, not per key. Creating more keys never buys more throughput.
  • Headers. Every response carries rate-limit headers (see Conventions).
  • Downgrades. If a shop moves to a plan without API access, its keys stop working with 402 API_NOT_IN_PLAN. The keys aren't deleted; they work again when the shop upgrades.

Quick start

curl https://app.blackbeachpos.com/api/v1/me \
  -H "Authorization: Bearer ir_live_4Tq…"

{
  "status": "ok",
  "data": {
    "object": "api_key",
    "id": 12,
    "name": "Flxpoint",
    "key": "ir_live_4Tq9…Xa2P",
    "environment": "live",
    "scopes": { "products": "write", "inventory": "write", "orders": "write", "customers": "read", "customer_dob": "none", "...": "..." },
    "location_ids": null,
    "shop": { "id": 17, "name": "Wick & Ember Candle Co.", "slug": "wick-ember", "plan": "enterprise" },
    "rate_limit": { "per_minute": 600, "per_day": null },
    "api_version": "2026-09-24"
  }
}

Contents

Basics

  • Authentication: keys, environments, IP allowlists, location limits, rolling and revoking.
  • Permissions: the scope grid, and what's never available.
  • Conventions: envelope, errors, money, dates, pagination, sync, idempotency, rate limits.

Resources

Webhooks: Webhooks covers the event catalog, signatures and retries.

Guides

Also: Sandbox · Changelog · machine-readable spec: openapi.yaml

Questions: hello@madfishsolutions.com.