BENCHTILL DEVELOPER API v1

Connect the systems
your business relies on.

Bring BenchTill records into your reporting tools and connect customer and appointment workflows to your own applications. Each integration receives the access its owner approves.

API base URLhttps://www.benchtill.com/integrations/v1

Access you control

Choose the shops and permissions for each integration. Keys can have an owner-selected expiry and can be revoked from your Master Portal.

A documented contract

Use consistent JSON responses, cursor pagination and an OpenAPI specification to develop and test your connection.

This API provides record reads and customer and appointment writes. Payments, refunds, stock adjustments and payroll approvals use BenchTill’s existing POS workflows. A connector for another service still needs to be developed and tested against that service.

QUICK START

Create a connection in three steps.

  1. Create an access key

    As the owner, open Admin → Custom integrations. Name the connection, choose its shops and permissions, then select an expiry date.

  2. Save the key securely

    Copy the key when it is created. Store it in your application’s server environment or secret manager. It cannot be viewed again; revoke and replace it if lost.

  3. Make your first request

    Send the key in the Authorization header. Start with /me to confirm access, then request your approved shops.

cURL · confirm your connection
curl --fail-with-body \
  'https://www.benchtill.com/integrations/v1/me' \
  -H "Authorization: Bearer $BENCHTILL_API_KEY"

Set BENCHTILL_API_KEY securely on your server before running this example. Never put the key in a URL, website JavaScript, a mobile app bundle or a shared spreadsheet. Browser requests carrying an Origin header are rejected. For a public booking form, use the separate shop booking API or hosted booking link.

OWNER CONTROL

Give each integration the access it needs.

Permissions and approved shops are checked on every request. A key cannot choose another business or access an unapproved shop. Updating a shared customer requires access to every shop associated with that record.

Available API permissions
PermissionAccess
Loading permissions…

REQUEST RULES

Build predictable connections.

Shop scope

Per-shop endpoints require storeId. Get approved active shops from /stores. Store IDs belong to one business; they do not select a business.

Pagination

Paginated list endpoints accept limit from 1 to 100 and return nextCursor. Pass that cursor unchanged with the same endpoint, shop and filters. An empty cursor means the page is complete.

Money and time

Money fields ending in Minor are integer minor units: 1299 means £12.99 or C$12.99. Currency is explicit. Timestamps use ISO 8601; appointment availability follows the shop’s saved time zone.

Rate limits

Requests are limited per key. A 429 response includes Retry-After. Wait before retrying; do not create additional keys to bypass the limit.

Safe retries for writes

Customer and appointment writes require an Idempotency-Key header containing a UUID. Create it once for an operation, and reuse the same key and JSON body if the request times out or the response is uncertain. A changed request using that key returns a conflict. Never generate a new key just because you did not receive the response.

cURL · create a customer
curl --fail-with-body \
  'https://www.benchtill.com/integrations/v1/customers?storeId=YOUR_STORE_ID' \
  -H "Authorization: Bearer $BENCHTILL_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: YOUR_OPERATION_UUID' \
  --data '{"name":"Example customer","phone":"+447700900001","email":"[email protected]"}'

Replace the store ID and operation UUID with your own values. Customer details above are examples. Keep personal data out of application logs.

DATA SYNCHRONIZATION

Read saved records accurately.

Creation-date filters find records created in a period; they do not capture later edits, refunds or order receipts. Appointments support updatedSince. Re-read other records to refresh their current state. Owner-configured signed webhooks can notify your server about supported record changes. They contain references only, are delivered at least once, and do not form a complete or ordered change stream. Reconcile gaps by reading current records.

Sales include their saved signed amounts and tax snapshots. recordedTotalMinor, actualTenderTotalMinor and recognizedGoodsTotalMinor distinguish the receipt total, new tender and goods value, including exchanges and deposits. Missing historical tax details remain null. Item unitPriceDecimal preserves the saved decimal exactly, including fractional minor units; do not recalculate saved tax from it.

Contact updates apply to the business’s shared customer record. New contacts whose phone number already exists require owner review. Customer consent, internal device notes and acquisition costs are outside this API’s scope.

RUNNABLE QUICKSTART

Build a booking website with a server-held key.

Download the Node 24 reference application into a private folder. It shows services and available times for one approved shop, then creates an appointment through your own server. The browser never receives the BenchTill key.

  1. Choose one shop and one permission

    Create a dedicated key with only appointments.write, which also allows service and availability reads. Save the business UUID and shop ID returned by /me. Configure that shop's services, hours and capacity first.

  2. Run the example locally

    Follow the setup guide to configure the server environment, then run node server.cjs and open http://127.0.0.1:4300. Node's built-in SQLite stores pending operations and webhook receipts; no npm installation is required.

  3. Test a complete booking and a retry

    Use a disposable business. Select a returned UTC slot, submit a booking, then test an uncertain response with the same operation UUID. The sample persists the intent before sending it and refuses changed retries.

Read setup, troubleshooting and rollout limits

Download together: server.cjs · index.html · site.js · site.css

This is a single-instance reference app. It needs your own HTTPS proxy, abuse controls, privacy wording, persistent storage and acceptance testing before public use. It takes no payment and sends no messages. Existing BenchTill hosted booking links are also available.

RECORD CHANGE NOTIFICATIONS

Verify, save, then acknowledge.

In Workspace → Integration webhooks, the owner registers a public HTTPS endpoint for one shop and selected event types. Save the one-time bt_whsec_… signing secret separately from the API key. Delivery also requires the BenchTill operator to enable the integration worker.

Signature · exact raw request bytes
v1=hex(HMAC-SHA256(full_signing_secret,
  X-BenchTill-Timestamp + "." + raw_body))

The sample receiver at /webhooks/benchtill checks the signature, a five-minute timestamp window, schema, expected business and shop, then durably inserts the signed event ID before returning 204. Duplicate deliveries produce one inbox record across restarts. Never deduplicate only the delivery header: the event ID inside the signed body is the trusted identity.

Supported events: customer.created, customer.updated, appointment.created, appointment.updated, appointment.cancelled, repair.status_changed and sale.recorded. Payloads contain references, with no contact details or amounts. Fetch an approved resource using its own read scope.

Registration covers future matching changes only. Events may be duplicated or out of order; this is not an exhaustive financial, consent or inventory feed. The sample saves a durable inbox and does not run a downstream sync worker. The setup guide describes retry, dead-letter, endpoint replacement and reconciliation limits.

INVENTORY READS

Separate stock on hand from current availability.

/inventory.quantity remains the raw stock balance. It does not subtract reserved units. For the supported subset, read /inventory-availability with inventory.read and an approved storeId.

Inventory availability fields
FieldMeaning
onHandQuantitySaved physical stock balance.
customerReservedQuantityAll held allocations for active customer reservations.
exchangeHeldQuantityPrepared, settlement-pending and review-required exchange holds. Unknown settlement remains held.
availableQuantityStock on hand minus both holds, with a minimum of zero.

Only active, listed Accessories without serial-receipt history, a special-order flag or active repair special-order custody are included. Any recorded receiving serial excludes the product conservatively, even after release or if another shop recorded it. Serialized devices, bundles, parts and other categories are outside this release. Catalogue prices are saved selling prices; this endpoint does not calculate checkout tax, shipping or discounts.

Review external catalogue references

In Tools → Catalogue mapping, the owner chooses one store and product, enters the exact external product or variant reference, reviews the current price and quantity, then confirms the mapping. This does not sign in to or publish on Shopify, WooCommerce or another provider. Account names are descriptive labels, not verified connections.

Read /catalogue-mappings to obtain these reviewed references and live availability. Read all pages, including retired records: retired or unavailable mappings return zero mapping availability. Filtering only to active mappings does not supply retirement notices. Mapping identity cannot be silently changed; an owner retires and replaces it. Developer API keys have read-only access to these mappings.

cURL · observed availability
curl --fail-with-body \
  'https://www.benchtill.com/integrations/v1/inventory-availability?storeId=YOUR_STORE_ID&limit=50' \
  -H "Authorization: Bearer $BENCHTILL_API_KEY"

Availability is an observation, not a reservation or promise of stock. It can change immediately; multiple mappings do not allocate separate stock pools. This release does not accept online orders, reserve units, prevent overselling, synchronize a channel or emit stock-change webhooks. Re-read current records and reconcile complete pages. Provider authentication, order/payment/refund handling and transactional stock allocation need a separately built and tested connector.

API REFERENCE

Supported endpoints.

Expand an endpoint for its permissions, parameters and response fields. The downloadable OpenAPI contract is the complete reference for this version.

Loading API reference…

These credentials do not sign in to the POS, approve computers or authorize staff actions. Existing public booking links use their own limited access and do not accept developer keys.

TROUBLESHOOTING

Handle the response, preserve the request.

Common API responses
StatusWhat to do
400 · Invalid requestCheck required fields, query parameters and their allowed formats.
401 · Invalid keyCheck the Authorization header and whether the key has expired or been revoked.
402 · Business access endedAsk the owner to renew the business’s access before retrying.
403 · Access deniedCheck the key’s permissions and approved shops. Send requests from your server.
404 · Record unavailableThe record may not exist within the approved shop.
409 · ConflictCheck the error code. Keep the original idempotency key when recovering an uncertain write.
429 · Rate limitWait for Retry-After, then retry the same request.
5xx · Service unavailableRetry reads with a delay. Retry writes with their original idempotency key and unchanged body.

Error responses contain an error, a machine-readable code and a requestId. Give support the request ID when reporting a problem; never send your API key.

Revoking a key blocks subsequent requests. An operation already admitted before revocation may finish. Revoking a key does not undo records already created.