REST API reference

BookingKoala API

15 endpoints for BookingKoala. Each one is a POST with a JSON body, called with your API key.

Base URL
https://cotlet.dev/api/v1/bookingkoala
Connects with
Your BookingKoala admin or staff account
Integration page
BookingKoala
BookingKoala Endpoints
Endpoint Access Description
list_bookings read Bookings with customer, services, date, arrival time, provider and price.
get_booking read Full booking: services, address, provider, price and job length adjustments, notes and charges.
list_customers read Customers with name, email, phone, addresses and number of bookings.
list_providers read Providers and teams, active or not, with their bookings on a given day.
list_charges read Booking charges with amount, status, card or cash/check, and refunds.
list_invoices read Invoices from the Invoice Dashboard with customer, amount and due date.
get_provider_payments read Amount due per provider for a pay period and amount owed up to today.
create_booking write New booking for an existing or new customer, with a provider or left in the unassigned folder.
reschedule_booking write Move a booking to a new date and arrival time.
assign_provider write Assign a provider or team to a booking, or pair providers for it.
add_booking_note write Add a private booking note, a private customer note or a note for the service provider.
cancel_booking write Cancel a booking, with or without the cancellation fee and the provider's share of it.
send_quote write Email a saved quote with an expiry date, reminder and optional offer.
refund_charge write Full or partial refund of a charge. One refund per charge.
resend_invoice write Resend an unpaid invoice to the customer.

List bookings

read

POST https://cotlet.dev/api/v1/bookingkoala/list_bookings

Lists bookings in one folder: upcoming, unassigned, drafts and quotes, or cancelled. Filter by date range, customer or provider. Pages follow the order of the folder; pass next_cursor back as cursor. Quotes in drafts_quotes carry the quote_id that send_quote needs.

Parameters

Parameters: list_bookings
NameTypeDescription
folder enum upcoming, unassigned, drafts_quotes or cancelled. Default: upcoming.
from date Only bookings on or after this date.
to date Only bookings on or before this date.
customer_id string Only bookings of this customer.
provider_id string Only bookings of this provider or team.
cursor string Next page cursor from the previous call.

Request

cURL
curl -X POST https://cotlet.dev/api/v1/bookingkoala/list_bookings \
  -H "Authorization: Bearer $COTLET_API_KEY"
Python
result = client.call("bookingkoala", "list_bookings")
Node.js
const result = await cotlet.call('bookingkoala', 'list_bookings');
CLI
cotlet call bookingkoala list_bookings

Example response

{
  "bookings": [
    {
      "booking_id": "48213",
      "customer": {
        "customer_id": "1207",
        "name": "Sarah Miller"
      },
      "services": [
        "Deep clean"
      ],
      "arrival": "2026-10-15T09:00:00-05:00",
      "provider": null,
      "folder": "unassigned",
      "price": "180.00"
    }
  ],
  "next_cursor": null
}

Get booking

read

POST https://cotlet.dev/api/v1/bookingkoala/get_booking

Returns one booking with its services, service address, assigned provider or team, price and job length adjustments, notes and charges. Use it before changing a booking so your agent sees its current state.

Parameters

Parameters: get_booking
NameTypeDescription
booking_id required string Booking ID from list_bookings.

Request

cURL
curl -X POST https://cotlet.dev/api/v1/bookingkoala/get_booking \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"booking_id":"booking_8c41d2"}'
Python
result = client.call("bookingkoala", "get_booking", {"booking_id":"booking_8c41d2"})
Node.js
const result = await cotlet.call('bookingkoala', 'get_booking', {"booking_id":"booking_8c41d2"});
CLI
cotlet call bookingkoala get_booking --data '{"booking_id":"booking_8c41d2"}'

Example response

{
  "booking_id": "48213",
  "customer": {
    "customer_id": "1207",
    "name": "Sarah Miller"
  },
  "services": [
    "Deep clean"
  ],
  "address": "14 Maple Street, Austin, TX",
  "arrival": "2026-10-15T09:00:00-05:00",
  "provider": {
    "id": "312",
    "name": "Team Blue"
  },
  "price": "180.00",
  "notes": [
    {
      "type": "private_booking",
      "text": "Gate code 4417"
    }
  ],
  "charges": [
    {
      "charge_id": "90417",
      "amount": "50.00",
      "status": "charged"
    }
  ]
}

List customers

read

POST https://cotlet.dev/api/v1/bookingkoala/list_customers

Lists customers, or searches them by name, email or phone. Each customer comes with addresses and a booking count. Use customer_id with list_bookings or create_booking. Pass next_cursor back as cursor for the next page.

Parameters

Parameters: list_customers
NameTypeDescription
query string Search by name, email or phone.
limit integer Customers per page.
cursor string Next page cursor from the previous call.

Request

cURL
curl -X POST https://cotlet.dev/api/v1/bookingkoala/list_customers \
  -H "Authorization: Bearer $COTLET_API_KEY"
Python
result = client.call("bookingkoala", "list_customers")
Node.js
const result = await cotlet.call('bookingkoala', 'list_customers');
CLI
cotlet call bookingkoala list_customers

Example response

{
  "customers": [
    {
      "customer_id": "1207",
      "name": "Sarah Miller",
      "email": "sarah@example.com",
      "phone": "+1 555 0100",
      "addresses": [
        "14 Maple Street, Austin, TX"
      ],
      "bookings": 6
    }
  ],
  "next_cursor": null
}

List providers

read

POST https://cotlet.dev/api/v1/bookingkoala/list_providers

Lists providers and teams, active or not. Pass a date to see each provider's bookings that day, which shows who has room. Use the id as provider_id in list_bookings, create_booking and assign_provider.

Parameters

Parameters: list_providers
NameTypeDescription
date date Show each provider's bookings on this day.

Request

cURL
curl -X POST https://cotlet.dev/api/v1/bookingkoala/list_providers \
  -H "Authorization: Bearer $COTLET_API_KEY"
Python
result = client.call("bookingkoala", "list_providers")
Node.js
const result = await cotlet.call('bookingkoala', 'list_providers');
CLI
cotlet call bookingkoala list_providers

Example response

{
  "providers": [
    {
      "id": "312",
      "name": "Team Blue",
      "type": "team",
      "active": true,
      "bookings_on_date": 3
    },
    {
      "id": "318",
      "name": "Marcus Reed",
      "type": "provider",
      "active": true,
      "bookings_on_date": 1
    }
  ]
}

List charges

read

POST https://cotlet.dev/api/v1/bookingkoala/list_charges

Lists charges from Booking Charges, newest first, with amount, status, payment method and any refund. Filter by booking or by charge date. The charge_id goes to refund_charge.

Parameters

Parameters: list_charges
NameTypeDescription
booking_id string Only charges of this booking.
from date Charged on or after this date.
to date Charged on or before this date.

Request

cURL
curl -X POST https://cotlet.dev/api/v1/bookingkoala/list_charges \
  -H "Authorization: Bearer $COTLET_API_KEY"
Python
result = client.call("bookingkoala", "list_charges")
Node.js
const result = await cotlet.call('bookingkoala', 'list_charges');
CLI
cotlet call bookingkoala list_charges

Example response

{
  "charges": [
    {
      "charge_id": "90417",
      "booking_id": "48213",
      "amount": "50.00",
      "status": "charged",
      "method": "card",
      "charged_at": "2026-10-15T12:30:00-05:00",
      "refunded": "0.00"
    }
  ]
}

List invoices

read

POST https://cotlet.dev/api/v1/bookingkoala/list_invoices

Lists invoices from the Invoice Dashboard, the active ones or the ones on the Overdue tab. Each has customer, amount and due date. The invoice_id goes to resend_invoice.

Parameters

Parameters: list_invoices
NameTypeDescription
status enum active or overdue. Default: active.

Request

cURL
curl -X POST https://cotlet.dev/api/v1/bookingkoala/list_invoices \
  -H "Authorization: Bearer $COTLET_API_KEY"
Python
result = client.call("bookingkoala", "list_invoices")
Node.js
const result = await cotlet.call('bookingkoala', 'list_invoices');
CLI
cotlet call bookingkoala list_invoices

Example response

{
  "invoices": [
    {
      "invoice_id": "inv_7710",
      "customer": {
        "customer_id": "1207",
        "name": "Sarah Miller"
      },
      "amount": "240.00",
      "due_date": "2026-10-01",
      "status": "overdue"
    }
  ]
}

Get provider payments

read

POST https://cotlet.dev/api/v1/bookingkoala/get_provider_payments

Returns, per provider, the amount due for the pay period you give and the amount owed up to today, the same two figures as Provider Payments in BookingKoala. The amount owed up to today is never lower than the amount due for the period. It is read only: it does not pay anyone.

Parameters

Parameters: get_provider_payments
NameTypeDescription
from required date Start of the pay period.
to required date End of the pay period.

Request

cURL
curl -X POST https://cotlet.dev/api/v1/bookingkoala/get_provider_payments \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"from":"2026-10-01","to":"2026-10-01"}'
Python
result = client.call("bookingkoala", "get_provider_payments", {"from":"2026-10-01","to":"2026-10-01"})
Node.js
const result = await cotlet.call('bookingkoala', 'get_provider_payments', {"from":"2026-10-01","to":"2026-10-01"});
CLI
cotlet call bookingkoala get_provider_payments --data '{"from":"2026-10-01","to":"2026-10-01"}'

Example response

{
  "from": "2026-09-28",
  "to": "2026-10-11",
  "providers": [
    {
      "id": "312",
      "name": "Team Blue",
      "amount_due": "1240.00",
      "owed_to_date": "1240.00"
    },
    {
      "id": "318",
      "name": "Marcus Reed",
      "amount_due": "610.00",
      "owed_to_date": "730.00"
    }
  ],
  "total_due": "1850.00"
}

Create booking

write Confirm

POST https://cotlet.dev/api/v1/bookingkoala/create_booking

Creates a booking for an existing customer, or for a new one when you pass a name and email. Without provider_id the booking waits in the unassigned folder. save_as can store it as a draft or a quote instead. Returns the booking_id and its folder. By default you confirm each call; you can switch that off for this tool.

Parameters

Parameters: create_booking
NameTypeDescription
customer required object customer_id, or first_name, last_name and email for a new customer.
services required object Industry and the services or extras picked on the booking form.
arrival required datetime Date and arrival time, ISO 8601 with time zone.
address string Service address. Default: the customer's existing address.
provider_id string Provider or team. Omit to leave the booking unassigned.
payment enum existing_card or cash_check. Default: existing_card.
save_as enum booking, draft or quote. Default: booking.

Request

cURL
curl -X POST https://cotlet.dev/api/v1/bookingkoala/create_booking \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"customer":{"customer_id":"1207"},"services":{"industry":"Home cleaning","services":["Deep clean"]},"arrival":"2026-10-13T09:00:00-05:00","payment":"existing_card","save_as":"booking"}'
Python
result = client.call("bookingkoala", "create_booking", {"customer":{"customer_id":"1207"},"services":{"industry":"Home cleaning","services":["Deep clean"]},"arrival":"2026-10-13T09:00:00-05:00","payment":"existing_card","save_as":"booking"})
Node.js
const result = await cotlet.call('bookingkoala', 'create_booking', {"customer":{"customer_id":"1207"},"services":{"industry":"Home cleaning","services":["Deep clean"]},"arrival":"2026-10-13T09:00:00-05:00","payment":"existing_card","save_as":"booking"});
CLI
cotlet call bookingkoala create_booking --data '{"customer":{"customer_id":"1207"},"services":{"industry":"Home cleaning","services":["Deep clean"]},"arrival":"2026-10-13T09:00:00-05:00","payment":"existing_card","save_as":"booking"}'

Example response

{
  "booking_id": "48377",
  "status": "upcoming",
  "folder": "upcoming",
  "arrival": "2026-10-12T09:00:00-05:00",
  "customer": {
    "customer_id": "1207",
    "name": "Sarah Miller"
  },
  "provider": null,
  "payment": "cash_check"
}

Reschedule booking

write Confirm

POST https://cotlet.dev/api/v1/bookingkoala/reschedule_booking

Moves one booking to a new date and arrival time and returns the updated booking. The assigned provider or team stays unless keep_provider is false. Rescheduling fees are set in BookingKoala; check them before moving many jobs. By default you confirm each call; you can switch that off for this tool.

Parameters

Parameters: reschedule_booking
NameTypeDescription
booking_id required string Booking ID from list_bookings.
arrival required datetime New date and arrival time, ISO 8601 with time zone.
keep_provider boolean Keep the assigned provider or team. Default: true.

Request

cURL
curl -X POST https://cotlet.dev/api/v1/bookingkoala/reschedule_booking \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"booking_id":"48213","arrival":"2026-10-16T10:00:00-05:00","keep_provider":true}'
Python
result = client.call("bookingkoala", "reschedule_booking", {"booking_id":"48213","arrival":"2026-10-16T10:00:00-05:00","keep_provider":True})
Node.js
const result = await cotlet.call('bookingkoala', 'reschedule_booking', {"booking_id":"48213","arrival":"2026-10-16T10:00:00-05:00","keep_provider":true});
CLI
cotlet call bookingkoala reschedule_booking --data '{"booking_id":"48213","arrival":"2026-10-16T10:00:00-05:00","keep_provider":true}'

Example response

{
  "booking_id": "48213",
  "status": "upcoming",
  "arrival": "2026-10-16T10:00:00-05:00",
  "provider": {
    "id": "312",
    "name": "Team Blue"
  }
}

Assign provider

write Confirm

POST https://cotlet.dev/api/v1/bookingkoala/assign_provider

Assigns one provider or team to a booking, which takes it out of the unassigned folder. Pass several provider_ids to pair providers on one booking; that needs provider pairing switched on in your BookingKoala scheduling permissions and on each provider. By default you confirm each call; you can switch that off for this tool.

Parameters

Parameters: assign_provider
NameTypeDescription
booking_id required string Booking ID from list_bookings.
provider_ids required string[] One provider or team, or several providers to pair.

Request

cURL
curl -X POST https://cotlet.dev/api/v1/bookingkoala/assign_provider \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"booking_id":"48213","provider_ids":["312"]}'
Python
result = client.call("bookingkoala", "assign_provider", {"booking_id":"48213","provider_ids":["312"]})
Node.js
const result = await cotlet.call('bookingkoala', 'assign_provider', {"booking_id":"48213","provider_ids":["312"]});
CLI
cotlet call bookingkoala assign_provider --data '{"booking_id":"48213","provider_ids":["312"]}'

Example response

{
  "booking_id": "48213",
  "status": "assigned",
  "folder": "upcoming",
  "providers": [
    {
      "id": "312",
      "name": "Team Blue"
    }
  ]
}

Add booking note

write Confirm

POST https://cotlet.dev/api/v1/bookingkoala/add_booking_note

Adds a note to a booking. private_booking and private_customer notes are for your team only; for_provider is shown to the service provider, so it reaches another person. Returns the note_id. By default you confirm each call; you can switch that off for this tool.

Parameters

Parameters: add_booking_note
NameTypeDescription
booking_id required string Booking ID from list_bookings.
type required enum private_booking, private_customer or for_provider.
text required string Note text.

Request

cURL
curl -X POST https://cotlet.dev/api/v1/bookingkoala/add_booking_note \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"booking_id":"booking_8c41d2","type":"private_booking","text":"text"}'
Python
result = client.call("bookingkoala", "add_booking_note", {"booking_id":"booking_8c41d2","type":"private_booking","text":"text"})
Node.js
const result = await cotlet.call('bookingkoala', 'add_booking_note', {"booking_id":"booking_8c41d2","type":"private_booking","text":"text"});
CLI
cotlet call bookingkoala add_booking_note --data '{"booking_id":"booking_8c41d2","type":"private_booking","text":"text"}'

Example response

{
  "note_id": "n_5521",
  "booking_id": "48213",
  "type": "for_provider",
  "status": "added"
}

Cancel booking

write Confirm

POST https://cotlet.dev/api/v1/bookingkoala/cancel_booking

Cancels one booking and moves it to the cancelled folder. charge_fee false cancels without your cancellation fee. pay_provider false skips the provider's share of the fee. reason takes one of the cancellation reasons you set up in BookingKoala. By default you confirm each call; you can switch that off for this tool.

Parameters

Parameters: cancel_booking
NameTypeDescription
booking_id required string Booking ID from list_bookings.
charge_fee boolean Charge your cancellation fee. Default: true.
pay_provider boolean Pay the provider out of the fee. Default: true.
reason string One of your cancellation reasons, if set up.

Request

cURL
curl -X POST https://cotlet.dev/api/v1/bookingkoala/cancel_booking \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"booking_id":"booking_8c41d2"}'
Python
result = client.call("bookingkoala", "cancel_booking", {"booking_id":"booking_8c41d2"})
Node.js
const result = await cotlet.call('bookingkoala', 'cancel_booking', {"booking_id":"booking_8c41d2"});
CLI
cotlet call bookingkoala cancel_booking --data '{"booking_id":"booking_8c41d2"}'

Example response

{
  "booking_id": "48213",
  "status": "cancelled",
  "folder": "cancelled",
  "fee_charged": false,
  "reason": "Customer request"
}

Send quote

write Confirm

POST https://cotlet.dev/api/v1/bookingkoala/send_quote

Emails a quote saved in the drafts and quotes folder to the customer, with an optional expiry date, reminder and offer. Returns the recipient and expiry. By default you confirm each call; you can switch that off for this tool.

Parameters

Parameters: send_quote
NameTypeDescription
quote_id required string Quote ID from list_bookings with folder drafts_quotes.
to string Recipient email. Default: the customer's email.
expires_on date Expiry date of the quote link.
reminder_days integer Send a reminder after this many days.
offer string Discount, e.g. "10%" or "$20".

Request

cURL
curl -X POST https://cotlet.dev/api/v1/bookingkoala/send_quote \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"quote_id":"quote_8c41d2"}'
Python
result = client.call("bookingkoala", "send_quote", {"quote_id":"quote_8c41d2"})
Node.js
const result = await cotlet.call('bookingkoala', 'send_quote', {"quote_id":"quote_8c41d2"});
CLI
cotlet call bookingkoala send_quote --data '{"quote_id":"quote_8c41d2"}'

Example response

{
  "quote_id": "q_3302",
  "status": "sent",
  "to": "sarah@example.com",
  "expires_on": "2026-10-25"
}

Refund charge

write Confirm

POST https://cotlet.dev/api/v1/bookingkoala/refund_charge

Refunds a charge in full, or in part when you pass amount; a partial amount includes tax. BookingKoala allows one refund per transaction, so a second refund on the same charge fails. The reason shows on the booking. notify false skips the customer notification. By default you confirm each call; you can switch that off for this tool.

Parameters

Parameters: refund_charge
NameTypeDescription
charge_id required string Charge ID from list_charges.
amount string Partial refund including tax. Omit for a full refund.
reason required string Reason shown on the booking.
notify boolean Notify the customer. Default: true.

Request

cURL
curl -X POST https://cotlet.dev/api/v1/bookingkoala/refund_charge \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"charge_id":"charge_8c41d2","reason":"reason"}'
Python
result = client.call("bookingkoala", "refund_charge", {"charge_id":"charge_8c41d2","reason":"reason"})
Node.js
const result = await cotlet.call('bookingkoala', 'refund_charge', {"charge_id":"charge_8c41d2","reason":"reason"});
CLI
cotlet call bookingkoala refund_charge --data '{"charge_id":"charge_8c41d2","reason":"reason"}'

Example response

{
  "charge_id": "90417",
  "status": "refunded",
  "charge_amount": "50.00",
  "refunded": "25.00",
  "reason": "Kitchen not finished, half refunded"
}

Resend invoice

write Confirm

POST https://cotlet.dev/api/v1/bookingkoala/resend_invoice

Resends one unpaid invoice to its customer, the same as Resend in the Actions menu of the Invoice Dashboard. Returns the send time. By default you confirm each call; you can switch that off for this tool.

Parameters

Parameters: resend_invoice
NameTypeDescription
invoice_id required string Invoice ID from list_invoices.

Request

cURL
curl -X POST https://cotlet.dev/api/v1/bookingkoala/resend_invoice \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"invoice_id":"invoice_8c41d2"}'
Python
result = client.call("bookingkoala", "resend_invoice", {"invoice_id":"invoice_8c41d2"})
Node.js
const result = await cotlet.call('bookingkoala', 'resend_invoice', {"invoice_id":"invoice_8c41d2"});
CLI
cotlet call bookingkoala resend_invoice --data '{"invoice_id":"invoice_8c41d2"}'

Example response

{
  "invoice_id": "inv_7710",
  "status": "resent",
  "to": "sarah@example.com",
  "sent_at": "2026-10-12T08:00:00-05:00"
}