Partner API · v1
Connect your system to PALAU EXPLORER
A machine-to-machine REST API for travel agencies. Read our tours, off-road and jet-ski departures with your own net rates, check live availability, create and cancel reservations, and reconcile your account.
Server-to-server only. Never put a key in a browser, mobile app or public repository.
Base URL
https://palauexplorer.com/api/v1
Authentication
Bearer API key, issued per agency
Rate limit
120 requests per minute per key
Format
JSON over HTTPS, UTF-8
Currency and dates
USD amounts as strings with two decimals. Dates as YYYY-MM-DD, timestamps in RFC 3339.
Support
info@palauexplorer.comOverview
The partner API is a machine-to-machine channel for travel agencies. It serves tours, off-road departures and jet-ski departures. Hotels are not bookable through this API.
Read
Published products, descriptions, images and your net rates.
Book
Live availability, reservations with idempotent writes, and cancellations.
Reconcile
Your invoices, payments and balance for a travel window.
Every call is scoped, rate limited and logged. A key always belongs to one agency and can only read or change the data of that agency.
Getting access
The API is open to travel agencies with a partner agreement. There is no self-service signup: every agency and every key is set up by our team.
- Contact our partner team with your company name, country, website, technical contact and expected monthly volume.
- We agree your commission rate, cancellation schedule and payment terms, then create your agency record.
- We issue a test key. It reads real catalog and availability data, but the bookings it writes are test records that never reserve stock or count in your statement.
- You build and test the integration against the test key.
- When you are ready, send us the fixed IP addresses your system will call from. We allowlist them and issue a live key.
- Switch the token, run the go-live checks below and start booking.
Keys and authentication
Send the key as a bearer token on every authenticated call:
Authorization: Bearer pk_live_01J4Z9K8YQ7V6N5M4P3R2S1T0H.7fK2pQ9wLm4Rx8Tn6Vb1Yc3Ds5Gh0Jk2Mn4Po6Qr8St0Uv
| Key | What it does |
|---|---|
pk_test_ |
Reads real data. Writes test bookings that never reserve stock, count in revenue or appear in a statement. |
pk_live_ |
Reads and writes real data. Reservations take stock immediately. |
Key rules
- The secret is shown once when the key is issued and stored only as a hash. If it is lost, rotate the key. It cannot be recovered.
- A key can be restricted to IPv4 or IPv6 addresses and CIDR blocks. A call from anywhere else returns 403 ip_not_allowed.
- Rotation issues a replacement and revokes the old secret in one step. Deploy the new token immediately, or plan a short maintenance window.
- Revocation is immediate. A suspended agency receives 403 agency_suspended on every call.
- The mode in the token must match the key. A test token cannot be used with a live key, or the reverse.
- Keep the key in a secret manager on your server. Never embed it in a browser, mobile app or public repository.
First calls
Run these three calls before writing any business logic. They prove reachability, credentials and commercial terms in that order.
1. Reachability
This call needs no key. It returns the server clock and proves that DNS, TLS and your outbound firewall are open.
curl https://palauexplorer.com/api/v1/ping
2. Who am I
This call needs a valid key but no scope. It returns your agency, the key mode, the scopes you hold and your rate limit.
curl https://palauexplorer.com/api/v1/me \ -H "Authorization: Bearer $PALAU_API_KEY"
{
"data": {
"agency": { "id": 7, "name": "Blue Lagoon Travel" },
"key": { "name": "Production integration", "mode": "live" },
"scopes": ["catalog.read", "inventory.read", "bookings.read", "bookings.write"],
"rate_limit": { "per_minute": 120 },
"status": "active"
}
}
3. Your commercial terms
This call returns the commission, cancellation schedule and payment terms agreed for your agency. Check them against your signed contract before you quote a customer.
curl https://palauexplorer.com/api/v1/terms \ -H "Authorization: Bearer $PALAU_API_KEY"
Wiring checklist
- GET /ping returns 200 with status ok.
- GET /me returns the expected agency and key mode.
- GET /me lists every scope you asked for.
- GET /terms matches your signed commission and cancellation schedule.
- A 401 means the key is missing, malformed, unknown, revoked or expired.
- A 403 means the key is valid but the agency is suspended, a scope is missing, or your address is not allowlisted.
Scopes
A key holds a set of scopes. A call that needs a scope the key does not hold returns 403 insufficient_scope. Ask for the smallest set your integration needs.
| Scope | Allows |
|---|---|
catalog.read |
Read the catalog Tours and off-road departures: descriptions, images and prices net of commission. |
inventory.read |
Read live inventory Per-day availability for tours and per-slot seat availability for off-road departures. |
bookings.read |
Read its own bookings The reservations this agency has made, and their status. |
bookings.write |
Create and cancel bookings Create and cancel reservations on this agency's behalf. |
Catalog and inventory are separate grants on purpose: a partner may buy the content without live stock, or the reverse. Writes are separate again, so a reconciliation job can read bookings without being able to create or cancel one.
This version has 15 routes under /v1. The full list is in the endpoint table below and in the OpenAPI contract.
Catalog
The catalog is read-only. It returns published products with your own net rates for a reference date. Pass locale=en, zh-Hans or ja; missing translations fall back to English.
Tours
GET /tourslists published, titled tours. Paginate with page and per_page; the maximum page size is 200.GET /tours/{slug}opens one tour with its full description, itinerary, inclusions, exclusions, highlights, gallery and state permits.- Each card carries id, slug, title, copy, duration, capacity, weekdays, image and price. Use id as product.id when booking. Keep slug as your stable external reference.
- State permits are bought locally and cannot be booked through the API. Quote them separately, or your price will be short by the fee.
curl "https://palauexplorer.com/api/v1/tours?locale=en&date=2026-11-20&per_page=50" \ -H "Authorization: Bearer $PALAU_API_KEY"
Off-road and jet ski
Each product has one endpoint and two departures, morning and afternoon. The departure id in that response is the product.id a booking takes.
curl "https://palauexplorer.com/api/v1/off-road?date=2026-11-20" \ -H "Authorization: Bearer $PALAU_API_KEY" curl "https://palauexplorer.com/api/v1/jet-ski?date=2026-11-20" \ -H "Authorization: Bearer $PALAU_API_KEY"
What a price means
publicis what the public site charges.netis what your agency pays after your commission.rateis your commission percentage.child_publicandchild_netappear only when the product has a child rate.
A catalog price is a quote for the reference date. Availability and price are checked again when you create the booking.
Availability
Availability is live. A seat can be taken between your read and your write, so always treat a booking as the authoritative answer.
Tours
GET /tours/{slug}/availability returns every day in the window, including closed days. Each day carries state, remaining and price.
stateis bookable, full or closed.remainingis the number of seats left. It is null when the product is uncapped.priceis null when the day is closed or carries no price. A full day still has a price.- The window defaults to 90 days from today and may span at most 366 days. A past from date is moved to today. A to before from is 422 validation_failed.
curl "https://palauexplorer.com/api/v1/tours/rock-islands-tour/availability?from=2026-11-20&to=2026-12-20" \ -H "Authorization: Bearer $PALAU_API_KEY"
Off-road and jet ski
GET /off-road/availability and GET /jet-ski/availability return seats_remaining per departure and date. Only sellable dates appear, and zero means full.
The jet-ski response also carries a skis list for each date. Each ski has assignment, seats_remaining and guide. Pass the assignments you want in party.skis.
- A customer ski sells two seats. Each rider is one person at the seat price.
- The guide ski is the only ski that accepts party.pillion. Its rear saddle opens only when every other seat on the date is gone, so its seats_remaining stays zero until then.
- A ski cannot be named twice in one booking, and the pillion must be the guide ski.
curl "https://palauexplorer.com/api/v1/jet-ski/availability?from=2026-11-20&to=2026-11-27" \ -H "Authorization: Bearer $PALAU_API_KEY"
Create a booking
POST /bookings creates a reservation and takes stock immediately. It requires the bookings.write scope and an Idempotency-Key header.
| Header | Value |
|---|---|
Authorization |
Bearer pk_live_... |
Content-Type |
application/json |
Idempotency-Key |
Your unique key for this logical booking, up to 191 characters. Generate one per booking, not per retry. |
Tour payload
curl -X POST "https://palauexplorer.com/api/v1/bookings" \
-H "Authorization: Bearer $PALAU_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 6b0f0f7e-2f4a-4b31-9a8e-2d3c4b5a6f70" \
-d '{
"product": { "type": "tour", "id": 3 },
"date": "2026-11-20",
"party": { "adults": 2, "children": 1 },
"guest": { "name": "Ana Reyes", "email": "ana@example.com", "phone": "+680 555 0100" },
"partner_reference": "INV-2041",
"hold_ttl_minutes": 60
}'
Off-road and jet-ski payloads
An off-road booking names seats. A jet-ski booking names whole skis, each with a rider count.
{
"product": { "type": "off_road", "id": 1 },
"date": "2026-11-20",
"party": { "seats": 2 },
"guest": { "name": "Ana Reyes", "email": "ana@example.com" }
}
{
"product": { "type": "jet_ski", "id": 1 },
"date": "2026-11-20",
"party": {
"skis": [
{ "assignment": 13, "riders": 2 },
{ "assignment": 14, "riders": 1 }
],
"pillion": 12
},
"guest": { "name": "Ana Reyes", "email": "ana@example.com" }
}
Fields
product.typeis tour, off_road or jet_ski.product.idis the tour id from /tours, or the departure id from /off-road or /jet-ski.dateis the travel date in YYYY-MM-DD.end_dateis optional and only meaningful for a multi-day tour.partytakes adults and children for a tour, seats for off-road, and skis for jet ski.guest.emailmust be a valid address; it is where the traveller confirmation is sent.partner_referenceis echoed back and is the best place for your own booking number.hold_ttl_minutesis optional, from 5 to 10080. Omit it for an open reservation.
Idempotency
A repeat with the same Idempotency-Key and the same body replays the first response instead of creating a second booking. The same key with a different body returns 409 idempotency_conflict. Keys are remembered for 24 hours.
This is what makes a timeout safe: send the same key and body again, and you will learn the original outcome rather than risk a duplicate.
Response
{
"data": {
"reference": "PE-01J4Z9K8YQ7V6N5M4P3R2S1T0H",
"status": "unpaid",
"test": false,
"product": { "type": "tour", "id": 3, "name": "Rock Islands Kayak" },
"date": "2026-11-20",
"end_date": null,
"party": { "adults": 2, "children": 1, "seats": null },
"guest": { "name": "Ana Reyes", "email": "ana@example.com", "phone": "+680 555 0100" },
"partner_reference": "INV-2041",
"price": { "public": "300.00", "rate": "15.00", "commission": "45.00", "net": "255.00" },
"invoice": { "number": "BLT-000042", "amount": "255.00", "status": "outstanding" },
"hold_expires_at": "2026-11-20T12:00:00+00:00",
"cancel_reason": null,
"cancel_penalty": null,
"created_at": "2026-11-20T11:00:00+00:00"
}
}
A test-key booking returns test: true. Keep the reference: it is how you read, cancel and reconcile the booking later.
Manage bookings
A key only ever sees its own agency's bookings. Another agency's reference is a plain 404.
GET /bookingslists your reservations, newest first. Filter by status (unpaid, confirmed, cancelled), from and to travel dates, page and per_page.GET /bookings/{reference}returns one booking.POST /bookings/{reference}/cancelcancels it, releases its stock and records the penalty your cancellation schedule implies.
curl "https://palauexplorer.com/api/v1/bookings?status=unpaid&from=2026-11-01&to=2026-11-30" \ -H "Authorization: Bearer $PALAU_API_KEY" curl -X POST "https://palauexplorer.com/api/v1/bookings/PE-01J4Z9K8YQ7V6N5M4P3R2S1T0H/cancel" \ -H "Authorization: Bearer $PALAU_API_KEY"
Cancellation is naturally idempotent: cancelling an already-cancelled booking returns it unchanged, so a retry is safe. A booking that lapses because its hold expired carries cancel_reason hold_expired; one cancelled by you carries partner.
Reconciliation
GET /statement returns your invoices, payments and balance for a travel window. A booking belongs to the window its start date falls in, and a payment to the window of the booking it settles, whenever the money arrived.
- The window defaults to the current month. A to earlier than from is 422 validation_failed.
- An invoice is outstanding, paid or void. A cancelled booking voids its invoice.
- The figures come from the same service the admin statement uses, so the two can never disagree.
curl "https://palauexplorer.com/api/v1/statement?from=2026-11-01&to=2026-11-30" \ -H "Authorization: Bearer $PALAU_API_KEY"
There are no partner webhooks. Poll GET /bookings for status changes and GET /statement for money. A five to fifteen minute interval is usually enough; do not poll on every page view.
Endpoints, errors and rate limits
Every path below is relative to the base URL. The scope a call needs is shown. "Any valid key" means no scope is checked.
| Method | Path | Scope |
|---|---|---|
| GET | /bookings |
bookings.read
|
| POST | /bookings |
bookings.write
|
| GET | /bookings/{reference} |
bookings.read
|
| POST | /bookings/{reference}/cancel |
bookings.write
|
| GET | /jet-ski |
catalog.read
|
| GET | /jet-ski/availability |
inventory.read
|
| GET | /me |
Any valid key |
| GET | /off-road |
catalog.read
|
| GET | /off-road/availability |
inventory.read
|
| GET | /ping |
None (public) |
| GET | /statement |
bookings.read
|
| GET | /terms |
Any valid key |
| GET | /tours |
catalog.read
|
| GET | /tours/{tour} |
catalog.read
|
| GET | /tours/{tour}/availability |
inventory.read
|
Error envelope
Every failure has the same shape, whatever produced it. Branch on code, never on message.
{
"error": {
"code": "insufficient_scope",
"message": "This key may not do that.",
"details": {}
}
}
| Status | Code | When |
|---|---|---|
| 401 | invalid_credentials | Missing, malformed, unknown, revoked or expired key. |
| 403 | agency_suspended | The key is valid but its agency is suspended. |
| 403 | insufficient_scope | The key lacks the scope the route requires. |
| 403 | ip_not_allowed | The caller is not in the address list of the key. |
| 404 | not_found | The resource does not exist, or belongs to another agency. |
| 409 | unavailable | The selection exists but cannot be sold: past, closed, full or unpriced. Re-read availability and re-quote. |
| 409 | idempotency_conflict | The Idempotency-Key was already used with a different body. |
| 422 | validation_failed | The request did not validate; details carries the field errors. |
| 429 | rate_limited | Too many requests. Wait for the Retry-After header. |
| 500 | server_error | Our fault. Nothing internal is leaked. Retry with backoff. |
Rate limits
- An authenticated key may make 120 requests per minute.
- An unauthenticated caller is limited to 30 requests per minute per address.
- A 429 carries Retry-After in seconds. Back off exponentially and add jitter; do not retry in a tight loop.
Retry policy
- Retry GET requests on 429 and 5xx with exponential backoff.
- Retry POST /bookings only with the same Idempotency-Key and the same body.
- Do not retry 401, 403, 404 or 422. Those need a configuration or payload fix.
- On 409 unavailable, re-read availability and re-quote before deciding whether to try another date or departure.
Code recipes
These examples create the same tour booking shown above. Replace the base URL, key and ids with your own.
PHP
use Illuminate\Support\Facades\Http;
use Illuminate\Support\Str;
$response = Http::withToken(config('services.palau.key'))
->withHeaders(['Idempotency-Key' => (string) Str::uuid()])
->post(config('services.palau.base_url').'/bookings', [
'product' => ['type' => 'tour', 'id' => 3],
'date' => '2026-11-20',
'party' => ['adults' => 2, 'children' => 1],
'guest' => [
'name' => 'Ana Reyes',
'email' => 'ana@example.com',
'phone' => '+680 555 0100',
],
'partner_reference' => 'INV-2041',
]);
if ($response->failed()) {
$error = $response->json('error');
// Branch on $error['code'], never on the message.
}
$booking = $response->json('data');
Node.js
const baseUrl = process.env.PALAU_API_BASE_URL;
const key = process.env.PALAU_API_KEY;
const response = await fetch(`${baseUrl}/bookings`, {
method: 'POST',
headers: {
Authorization: `Bearer ${key}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
product: { type: 'tour', id: 3 },
date: '2026-11-20',
party: { adults: 2, children: 1 },
guest: {
name: 'Ana Reyes',
email: 'ana@example.com',
phone: '+680 555 0100',
},
partner_reference: 'INV-2041',
}),
});
const payload = await response.json();
if (!response.ok) {
throw new Error(`Booking failed: ${payload.error.code}`);
}
const booking = payload.data;
Use a UUID or another unique value for the Idempotency-Key. Store it next to your own booking attempt so a timeout can be retried with the same value.
Go-live checklist
- Your live key is issued and restricted to your production egress addresses.
- The test key is not present in production configuration or logs.
- The key is stored in a secret manager, never in code or a public repository.
- Your HTTP client uses a connect timeout of about 10 seconds and a read timeout of about 30 seconds.
- Every booking attempt has a persisted Idempotency-Key, including retries.
- Your job polls /bookings and /statement on a schedule and alerts on 401, 403, 429 and 5xx.
- You have run a test booking end to end: create, read, cancel and reconcile.
- You know who rotates the key and how the new token reaches production.
- You have completed one live booking with a real customer before announcing the integration.
FAQ
Can I book hotels through this API?
No. The partner API covers tours, off-road departures and jet-ski departures. Hotel stays are not part of v1.
Is there a separate sandbox URL?
No. Use the same base URL with a pk_test_ key. Test reads return real data; test writes create test bookings that never reserve stock or count in your statement.
Can I call the API from a browser or mobile app?
No. The key is a server secret. Call from your own backend, where the key can be stored and rotated safely.
Do you send webhooks?
No partner webhooks exist in v1. Poll /bookings for status changes and /statement for money.
Why is a booking I just created returning 404?
A booking is only visible to the agency that created it. Check that you are using the same key, and that the reference is complete.
Are catalog prices final?
They are quotes for the reference date. The booking re-checks availability and price, and returns the final net amount. State permits are extra and are not bookable.
Where do I find the id for a tour or a ski?
The tour id is the id field on each /tours card. Ski assignment ids are the assignment values in the skis list of /jet-ski/availability.
Can the rate limit be raised?
Talk to your partner manager. The limit is per key contract, not a global ceiling.
How is the API versioned?
Everything lives under /v1. Additive fields may appear within the version. A breaking change means a new version, never a change under this one.
Still stuck?
Send us the request id, the endpoint, the timestamp and the error code. Never send a full key.
Contact the partner team