Developer docs menu

Building

Partners

Set businesses up for other people, and hand each one to its owner.

A partner is an organisation that sets businesses up for other people: an agency, or the maker of a receptionist product. A partner has its own key, which makes businesses and acts for the ones it made.

Making a business

curl -X POST https://api.bookingmachine.io/v1/partner/businesses \
  -H 'Authorization: Bearer bm_live_…' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: client-42' \
  -d '{
    "name": "Sparkle Cleaning",
    "slug": "sparkle-cleaning",
    "vertical": "house-cleaning",
    "timezone": "Europe/London",
    "currency": "GBP",
    "country": "GB",
    "hours": [{ "day": 1, "open": "09:00", "close": "17:00" }],
    "services": [{ "name": "Standard clean", "durationMinutes": 120, "price": 60 }]
  }'
  • It is an ordinary business on the Free plan, with a booking page at once.

  • hours left out gives Monday to Friday 08:00 to 18:00 and Saturday 09:00 to 15:00. Day 0 is Sunday.

  • starterServices: true in place of services starts it with the usual services for its industry. Their prices are starting figures, there to be changed.

  • Nobody is emailed, and payments stay off.

Acting for a business you made

The partner key works on every operation for a business the partner made, with every scope, whatever the business’s plan. On operations that name the business in the path, nothing more is needed. On /account operations, name it with a header:

curl https://api.bookingmachine.io/v1/account/bookings \
  -H 'Authorization: Bearer bm_live_…' \
  -H 'X-Business: sparkle-cleaning'

A booking made with a partner key is made directly and is recorded as coming from the partner. For any other business the key is refused with 403 partner_wrong_business.

Handing the business to its owner

curl -X POST https://api.bookingmachine.io/v1/partner/businesses/sparkle-cleaning/invite \
  -H 'Authorization: Bearer bm_live_…' \
  -H 'Content-Type: application/json' \
  -d '{ "email": "[email protected]" }'

The owner is emailed one link, good for 14 days. When they sign in with that address and accept, the business is theirs. Sending again replaces the link. A business can be invited 3 times a day.

After the owner takes over

  • The partner keeps a seat in the business’s team, which the owner can remove.

  • The partner key keeps working for the business while that seat is there. Once it is removed, the refusal is 403 partner_access_removed.

  • Only the owner can set up payments. A partner never holds a business’s payment account.

The partner portal

The account that runs a partner has a page at /partner on the main site: its businesses and whether each has been taken over, a way into each dashboard, the invitation form, and its own API keys.

Limits

A partner can have a set number of businesses at once. GET /partner shows how many it has and how many it may have. Past it, the refusal is 409 business_limit_reached.