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' });