Chauffeur Circle Docs

Developers

JavaScript SDK

ProBusiness Included on these plans

@chauffeurcircle/js is a small, typed client for the Public API. Use it in the browser with a publishable key for custom forms, or in Node with a secret key on your server.

Install

In the browser, load it from the CDN. It defines window.ChauffeurCircle:

<script src="https://cdn.chauffeurcircle.com/v1/sdk.js"></script>

As an ES module: import { ChauffeurCircle } from 'https://cdn.chauffeurcircle.com/v1/sdk.mjs'. An npm package is planned.

Create a client

const chauffeurCircle = ChauffeurCircle('cc_pk_live_…');
// Options: { apiBase: 'https://api.chauffeurcircle.com', fetch }

Using a secret key (cc_sk_…) in a browser throws an error on purpose.

Methods

Method Returns Key
config() Your branding, services, airports, extras, rules, policies, theme publishable or secret
quotes.create(trip) A quote with each vehicle and its price publishable or secret
bookings.create(booking, idempotencyKey?) { booking, payment_session } publishable or secret
bookings.get(reference, email) A booking. With a publishable key, pass the email used to book publishable or secret
bookings.cancel(reference, email, reason?) The cancelled booking (fee by your policy) publishable or secret
bookings.list(filters) { data, meta }, with passenger contact details secret only (Business)
payments.mount(element, options) { iframe, saved, unmount() } browser only
ChauffeurCircle.webhooks.verify(secret, header, rawBody) true / false server

quotes.create(trip)

await chauffeurCircle.quotes.create({
  service_type: 'point_to_point',          // or 'airport', 'hourly'
  pickup: { address, lat, lng },           // or { airport: 'JFK' }
  dropoff: { address, lat, lng },          // not needed for hourly
  stops: [],                               // up to 3
  pickup_at: '2026-06-10T10:00',           // without an offset: your time zone
  hours: null,                             // hourly only
  passengers: 2,
  luggage: 1,
  gratuity_bps: 2000,                      // optional, 2000 = 20%
  extras: [{ id: 3, quantity: 1 }],
});

bookings.create(booking)

const { booking, payment_session } = await chauffeurCircle.bookings.create({
  quote_id: quote.id,
  vehicle_type_id: 2,
  customer: { first_name: 'Ada', last_name: 'Lovelace', email: 'ada@example.com', phone: '+12127363100' },
  passenger: null,              // if someone else rides
  flight_number: 'BA117', airline: 'British Airways',
  notes: 'Meet at arrivals',
  terms_accepted: true,
  source: 'custom_form',
});

payments.mount(element, options)

const frame = chauffeurCircle.payments.mount('#card', {
  session: payment_session,          // or its frame_url
  onReady: () => {},
  onSuccess: ({ reference, brand, last4 }) => {},
  onError: ({ code, message }) => {},
});
await frame.saved;                   // resolves when the card is saved

Errors

Every failed call throws a ChauffeurCircleError with code, message, status and fields (for validation_failed):

try {
  await chauffeurCircle.bookings.create(input);
} catch (err) {
  if (err.code === 'validation_failed') showFieldErrors(err.fields);
  else if (err.code === 'quote_expired') refreshPrices();
  else showMessage(err.message);
}

See the error codes.

On your server (Node 18+)

import { ChauffeurCircle } from '@chauffeurcircle/js';

const chauffeurCircle = ChauffeurCircle(process.env.CHAUFFEUR_CIRCLE_SECRET_KEY);
const { data } = await chauffeurCircle.bookings.list({ status: 'new', from: '2026-06-01' });